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Introduction 



This document is intended for use with IBM® Cognos® Event Studio. Event Studio 
is a web-based product for creating and managing agents that monitor data and 
perform tasks when the data meets predefined thresholds. 

This document describes how to use Cognos Event Studio to ensure that critical 
information is detected quickly and delivered to key stakeholders in your business. 

Audience 

To use this guide, you should have 

• Knowledge of your business requirements. 

• Knowledge of business analysis concepts. 

• Knowledge of databases and data modeling concepts. 

Finding information 

To find IBM Cognos product documentation on the web, including all translated 
documentation, access one of the IBM Cognos Information Centers 
(http:/ / publib.boulder.ibm.com/infocenter/ cogic/vlrOmO /index.jsp). Release 
Notes are published directly to Information Centers, and include links to the latest 
technotes and APARs. 

You can also read PDF versions of the product release notes and installation guides 
directly from IBM Cognos product disks. 

Accessibility features 

IBM Cognos Event Studio does not currently support accessibility features that 
help users with a physical disability, such as restricted mobility or limited vision, 
to use this product. 

IBM Cognos HTML documentation has accessibility features. PDF documents are 
supplemental and, as such, include no added accessibility features. 

Forward-looking statements 

This documentation describes the current functionality of the product. References 
to items that are not currently available may be included. No implication of any 
future availability should be inferred. Any such references are not a commitment, 
promise, or legal obligation to deliver any material, code, or functionality. The 
development, release, and timing of features or functionality remain at the sole 
discretion of IBM. 

Samples disclaimer 

The Great Outdoors Company, GO Sales, any variation of the Great Outdoors 
name, and Planning Sample depict fictitious business operations with sample data 
used to develop sample applications for IBM and IBM customers. These fictitious 
records include sample data for sales transactions, product distribution, finance, 
and human resources. Any resemblance to actual names, addresses, contact 
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numbers, or transaction values is coincidental. Other sample files may contain 
fictional data manually or machine generated, factual data compiled from 
academic or public sources, or data used with permission of the copyright holder, 
for use as sample data to develop sample applications. Product names referenced 
may be the trademarks of their respective owners. Unauthorized duplication is 
prohibited. 
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Chapter 1. What's new? 



This section contains a list of new features for this release. It will help you plan 
your upgrade and application deployment strategies and the training requirements 
for your users. 

For an overview of new features for this release, see the IBM Cognos Business 
Intelligence New Features Guide. 

What's New information for past releases, including versions 8.3 and 8.4, is 
available by accessing documentation within the IBM Cognos Business Intelligence 
10.1.1 Information Center (http://publib.boulder.ibm.com/infocenter/cbi/ 
vlOrlml / index.jsp?lang=en). 

To review an up-to-date list of environments supported by IBM Cognos products, 
such as operating systems, patches, browsers, web servers, directory servers, 
database servers, and application servers, visit the IBM Cognos Information 
Centers (http: / / publib.boulder.ibm.com/infocenter/cogic / vlrOmO /index.jsp). 



New features in version 10.1.1 

Listed below are new features since the last release. Links to directly-related topics 
are included. 

New Human Tasks 

There are two new human tasks that you can create in IBM Cognos Event Studio: 
approval request tasks and notification request tasks. 

For more information, see "Add an Approval Request Task" on page 33 and "Add 
a Notification Request Task" on page 36. 
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Chapter 2. IBM Cognos Event Studio 



Use IBM Cognos Event Studio to notify decision-makers in your organization of 
events as they happen, so that they can make timely and effective decisions. 

You create agents that monitor your organization's data to detect occurrences of 
business events. An event is a situation that can affect the success of your business. 
An event is identified when specific items in your data achieve significant values. 
Specify the event condition, or a change in data, that is important to you. When an 
agent detects an event, it can perform tasks, such as sending an e-mail, adding 
information to the portal, and running reports. 

For information about how to use Cognos Event Studio, see Chapter 3, "Creating 
an Agent," on page 23. 

Note: Some of the features available in Cognos Event Studio are not compatible 
with Firefox. For this reason, you are recommended to use Microsoft Internet 
Explorer web browser. 

You can follow a tutorial that shows you how to create and run an agent in 
response to a business scenario. For more information, see Chapter 4, "Tutorial - 
Creating an Agent," on page 55. 

Source Items 

IBM Cognos Event Studio works with source items that were defined in an IBM 
Cognos Framework Manager model and published as a package to IBM Cognos 
Connection. Source items are used to specify an event condition that is monitored 
by the agent. You can also use source items to derive calculations or parameters 
that may be included in the event condition. 

To use Cognos Event Studio effectively, you should be familiar your organization's 
business and its data. You may also need to be familiar with other components of 
IBM Cognos Business Intelligence. 

IBM Cognos Report Studio 

IBM Cognos Report Studio is the professional reporting tool for IBM Cognos 
Business Intelligence. Use it to author more complex reports. 

Report Studio offers greater flexibility in calculating and formatting results. Report 
authors can open IBM Cognos Query Studio reports to create more advanced 
reports. 

Cognos Report Studio gives users access to the full range of Cognos Report Studio 
functionality. Use Cognos Report Studio to create any report type, including charts, 
maps, lists, and repeaters, using any data source (relational or multi-dimensional). 

IBM Cognos Business Insight 

IBM Cognos Business Insight is a new report consumption tool that provides an 
integrated business intelligence experience for business users. This web-based tool 
allows you to use IBM Cognos content and external data sources to build 
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sophisticated interactive dashboards that facilitate collaborative decision making. 

IBM Cognos Business Insight Advanced 

IBM Cognos Business Insight Advanced provides a simple and focused report 
authoring interface. It is designed for business users to create reports that analyze 
corporate data according to specific information needs. When you are consuming 
reports using IBM Cognos Business Insight, and you want to edit the report or 
author a new report, use Business Insight Advanced to do so. 

This new report authoring tool replaces IBM Cognos Report Studio Express®. 

IBM Cognos Connection 

IBM Cognos Connection is the web portal for IBM Cognos Business Intelligence. 
Use the portal to store and access your reports. If you have the necessary 
permissions, you can also use the portal for report administration, including 
scheduling and distributing reports. 

Administrators use the portal to administer servers, optimize performance, and 
specify access permissions. 

IBM Cognos Framework Manager 

IBM Cognos Framework Manager is the data modeling tool for IBM Cognos 
Business Intelligence. 

The packages you use to generate reports are based on models that are created in 
Cognos Framework Manager. A model is a set of related objects, such as query 
subjects, dimensions, filters, and calculations. When you open a package in Cognos 
Business Intelligence, these model objects are visible in the left frame. 

IBM Cognos Analysis Studio 

IBM Cognos Analysis Studio is the analysis tool for IBM Cognos Business 
Intelligence. Use it to explore, analyze, and compare dimensional data. 

Analysis Studio helps you answer business questions by finding meaningful 
information in large data sources. 

IBM Cognos Metric Studio 

IBM Cognos Metric Studio is the metrics tool for IBM Cognos Business 
Intelligence. Use it to create scorecard applications and monitor the metrics within 
them. 

Cognos Metric Studio helps you translate your organization's strategy into 
relevant, measurable goals that align each employee's actions with a strategic plan. 

IBM Cognos Query Studio 

IBM Cognos Query Studio is the reporting tool for creating simple queries and 
reports in IBM Cognos Business Intelligence, the web-based reporting solution. In 
Query Studio, you can view data, create reports, change the appearance of reports, 
and work with data in a report. 
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Building IBM Cognos Business Intelligence Applications 

You use the IBM Cognos Business Intelligence components to build reporting and 
analysis applications. 

The lifetime of an Cognos Business Intelligence application can be months, or even 
years. During that time, data may change and new requirements appear. As the 
underlying data changes, authors must modify existing content and develop new 
content. Administrators must also update models and data sources over time. For 
more information about using data sources, see the IBM Cognos Business 
Intelligence Administration and Security Guide and the IBM Cognos Framework 
Manager User Guide. 

Before you begin 

In a working application, the technical and security infrastructure and the portal 
are in place, as well as processes for change management, data control, and so on. 
For information about the workflow associated with creating Cognos BI content, 
see the IBM Cognos Business Intelligence Architecture and Deployment Guide. For 
additional information, see the IBM Cognos Solutions Implementation 
Methodology toolkit, which includes implementation roadmaps and supporting 
documents. Information about the toolkit is available on the IBM Cognos 
Information Centers (http:/ /publib.boulder.ibm.com/infocenter/cogic/vlrOmO/ 
index.jsp). 

The following graphic provides an overview for how to use Cognos BI to build 
applications across all of your Cognos BI components. 




Procedure 

1 . Locate and prepare data sources and models 

Cognos BI can report from a wide variety of data sources, both relational and 
dimensional. Database connections are created in the Web administration 
interface, and are used for modeling, for authoring, and for running the 
application. 

To use data for authoring and viewing, the business intelligence studios need a 
subset of a model of the metadata (called a package). The metadata may need 
extensive modeling in Cognos Framework Manager. 

2. Build and publish the content 

Reports, scorecards, analysis, dashboards and more are created in the business 
intelligence studios of Cognos BI. Which studio you use depends on the 
content, lifespan, and audience of the report, and whether the data is modeled 
dimensionally or relationally. For example, self-service reporting and analysis 
are done through IBM Cognos Business Insight Advanced, IBM Cognos Query 
Studio, and IBM Cognos Analysis Studio, and scheduled reports are created in 
IBM Cognos Report Studio. Report Studio reports and scorecards are usually 
prepared for a wider audience, published to IBM Cognos Connection or 
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another portal, and scheduled there for bursting, distribution, and so on. You 
can also use Cognos Report Studio to prepare templates for self-service 
reporting. 

3. Deliver and view the information 

You deliver content from the IBM Cognos portal or other supported portals, 
and view information that has been saved to portals, or delivered by other 
mechanisms. You can also run reports, analyses, scorecards, and more from 
within the business intelligence studio in which they were created. 

For information about tuning and performance, see the IBM Cognos Business 
Intelligence Administration and Security Guide and the IBM Cognos Information 
Centers (http://publib.boulder.ibm.com/infocenter/cogic/vlrOmO/index.jsp). 



The IBM Cognos Event Studio Window 

Use the IBM Cognos Event Studio window to interactively create and manage 
agents. 

The Cognos Event Studio window is made up of four areas: 

• the I want to area 

This area shows the main tasks that you perform when you create an agent. 

• the Insertable Objects area 

This area shows available source items, data items used by the current agent, 
functions you can insert in the event condition, and parameters you created. 

• the summary area 

This area contains tabs with summary descriptions of the event condition and of 
each task defined for the agent. 

• the content area 

This area contains the pages and dialogs that you use to create and manage an 
agent. 

The four areas are shown in the following example. 
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I want to area 



Summary area 




Insertable Objects area Content area 

Figure 1. Event Studio user interface work areas 



Insertable Objects Area 

The Insertable Objects area contains items that you can add to the event condition 
and tasks. There are several tabs along the bottom of this area. 

The Source Tab 



The source tab 



1 



shows a hierarchical list of the source items, both relational 



and dimensional, in the model package. 



The Data Items Tab 






shows a list of all the data items contained in the agent. 



The data items tab 
The data items tab also shows the calculations used in the agent. 



The Functions Tab 



The functions tab |fcj shows a list of mathematical functions, such as operators 
and summaries, that you can use in event conditions and to create calculated data 
items. 
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Tip: If you are specifying an event condition and want to know the meaning of a 
function icon, click the icon and read the description in the Information box. 

The Parameters Tab 



The parameters tab [jjg shows a list of each parameter you defined, indicated by 
the parameter icon. You can use parameters when specifying the event condition. 

The Run History Tab 



The run history tab [E| shows a list of items you can specify when you add an 
on-error task to an agent. 



Example - Create an Agent with a Single Task 

You create an agent to perform a task when it detects a business event. 

You are a sales manager who wants to ensure that your most valued customers are 
pleased with the quality of service they receive. 

You decide that, whenever a valued customer calls your support group, you will 
call the customer the next day to make sure they're satisfied. You use IBM Cognos 
Event Studio to create an agent that monitors support call records. You specify an 
event condition as follows: 

[Cal l_Status] = Open AND [Customer_Profi 1 e] = Gold 

Next you add a task and specify that, when the event occurs, the agent sends you 
an e-mail entitled Urgent: Call Customer Today. 

The e-mail message you receive contains details both about the customer and 
about the call. You do not need to continually check the call system or run reports. 
The relevant data is sent to you only when you need to act upon it. 



Events 



An event is an exceptional item of data, defined by specifying a query expression 
against items in a data package. When a record matches the event condition, it 
causes an agent to perform tasks. 

When an agent runs, it checks the data for any event instances. 

For example, you can specify an event condition as follows: 

[Account_Bal ance] < 0 

Event Instances 

An event instance is a single row of data that matches the event query expression. 
When an agent monitors data, it detects each event instance. The agent then 
follows the task execution rules to determine if it should perform a task. 

Some types of tasks are performed only once by the agent. Other types of tasks are 
repeated for each event instance. For more information, see "Task Frequency" on 
page 12. 
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Event List 

An event list shows the events processed by the agent. Each event is categorized 
by one of the following statuses: new, ongoing but changed, ongoing and 
unchanged, or ceased. 

When an agent runs, it derives the status by comparing the detected events with 
those detected in the previous run. There is only one event list per agent, and it is 
updated each time the agent runs. 

For each task in an agent, the event list is checked against the task execution rules. 
The task is performed for each event that conforms to the rules. 

Event Key 

An event key is used to determine whether an event is new, ongoing but changed, 
ongoing and unchanged, or ceased. IBM Cognos Event Studio compares the event 
instances detected in each agent run with those detected in the previous run. To 
ensure it correctly matches the event instances for comparison, you must define an 
event key. The event key is the combination of data items that uniquely defines an 
event instance. 

For example, you are dealing with orders that were placed for out-of-stock goods. 
You define Order Number as the event key, because each order placed has a unique 
number. If Order Number 1234 appears in this run and in the previous run, it is an 
ongoing event. If Order Number 4567 appears in this run, but not in the previous 
run, it is a new event. If Order Number 7890 appeared in the last run but not this 
one, it has ceased. 

Task Execution Rules 

When an agent runs, it uses the event key to compare the event instances it detects 
with those of the previous run. The agent allocates a status to each event - new, 
ongoing but changed, ongoing and unchanged, or ceased. If no event instances are 
detected, the status is no events. The task execution rules specify the event status 
for which each task is performed. You can optionally specify that an event must 
also pass a Boolean test before it is used in a task. If you do not set any execution 
rules, the agent performs its tasks for all the event instances it detects. 

You can also set a special task to execute if the agent fails, for example, if the agent 
condition fails or one of the agent's tasks fails to complete. This special task can 
include items from the agent's run history, such as its run time, status, and error 
messages. 

Example - Event Status of New 

You want to receive an e-mail message advising you whenever a Gold category 
customer phones technical support about a new problem. 

You specify that an e-mail task be performed only when the event status is new. 
You receive an e-mail when the call record from a Gold customer is first placed in 
the call database. However, even if the call record is still open the next time the 
agent runs, you receive no further e-mails because the status of the event is now 
ongoing. 
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Example - Event Status of Ongoing But Changed 

You want a report to run if the account balance of an overdrawn customer 
changes. 

Example - Event Status of No Events 

You want to receive a daily e-mail that reassures you that none of your company's 
accounts has a balance less than zero. 

You define the following event condition: 

[Account_Bal ance] < 0 

You specify that an e-mail task be performed if the event status is no events. 

In this example, you may also want to create another task that sends an urgent 
e-mail if any of the account balances does become less than zero. That is, you 
create another e-mail task that is performed if the event status is new. 

Example - Task-Level Boolean Filter 

You want to e-mail your Regional Managers whenever a very large order is 
received from a customer in their territory 

You create four calculated data items containing Boolean expressions: 

• Item IsNorth: If ([Region] = 'North') then ('True') else ('False') 

• Item IsEast: If ([Region] = 'East') then ('True') else ('False') 

• Item IsSouth: If ([Region] = 'South') then ('True') else ('False') 

• Item IsWest: If ([Region] = 'West') then ('True') else ('False') 

Add four e-mail tasks to the agent, one addressed to each Regional Manager. Add 
the appropriate task-level filter to each task. In this example, the task that e-mails 
the Northern Regional Manager includes only orders that pass the test Region = 
'North'. 


Agents 


Agents monitor data for instances of an event and perform tasks when events 
occur. These tasks can help to notify people about events immediately, so that they 
can make timely and effective decisions. 

When an agent runs, it checks for occurrences of the event. If it detects the event, 
the agent performs its tasks for events that meet the execution rules. An agent runs 
its tasks either all at the same time or in the order that you specify. 

Example - Create an Agent with Multiple Tasks 

You are a meteorological analyst who wants to be alerted to extreme drops in air 
pressure that could result in a violent storm. 

You create an agent named Pressure_Drop. You specify the event condition as 
follows: 

[Air Pressure] . [Current Time-60] - ([Air Pressure] . [Current Time])> 

5.0 
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Next, you add an e-mail task and specify that, when the event occurs, the agent 
sends you an e-mail entitled Pressure Drop Alert. Finally, you add a report task 
that sends a report of the latest air pressure readings to people in surrounding 
weather offices. 

Prompting Agents 

A prompting agent prompts a user to specify values for the event condition. This 
can result in the task being performed in a situation that is specific to the user. 

For example, you specify an event condition that prompts sales managers to 
specify their region and their product. The task is then performed only for events 
that are of interest to the sales manager who is running the agent. 

The prompts of an agent can also be answered by passing in the values of source 
items from the events of another agent. 

Agent Views 

You can use IBM Cognos Connection to create an agent view. Agent Views are 
used to share the agent specification. However, you can run an agent view using 
different prompt values if it is a prompting agent, or following a different 
schedule. 

For more information, see the IBM Cognos Connection User Guide. 



Tasks 

An agent can perform one or more tasks that you define for it. You can use some 
tasks to notify the right people quickly about a change in a business event so they 
can take appropriate action. Other tasks can help you to automate a work flow. 

An agent can perform its tasks all in sequence or all in parallel. That is, you can 
specify that each task is performed in the order you choose. Or you can specify 
that tasks be performed at the same time. 

You can specify tasks that do the following: 

• send an e-mail 

• publish a news item 

• run a report 

• run a job 

• run an agent 

• send an approval request 

• send a notification request 

• update a database 

• call a web service 

• run an export 

• run an import 

• run a content maintenance task 

• run a metric task 
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Task Frequency 

Before you specify an event condition, you should understand how often different 
tasks are performed. 



Task type 


Number of times performed 


Run a report; run an agent; run a job; run an 
import; run an export; run a metric task; run 
a content maintenance task 


Once 


Update a database; call a web service 


Once per event instance 


Send an e-mail; send an approval request; 
send a notification request 


Variable 

For more information, see "How Multiple 
Events Affect E-mail Messages, Approval 
Requests, and Notification Requests" on 
page 13. 


Publish a news item 


Once 



Notification Methods 

If you want to notify people about a business event, you should understand the 
notification methods that an agent can use. The notification method you choose 
should contain all information relevant to the event, and each person who must 
know about the event should be notified. 

An IBM Cognos Event Studio agent can notify people about business events by 

• delivering an email to your audience 

• publishing a news item to a folder frequently viewed by your audience 

The notification feature can contain dynamic information. This means that source 
items from a package can be inserted into the message. The values for these items 
are not retrieved until the agent is run because a notification message about a 
critical data item always contains the current values. 

Both e-mail and news item notifications can contain dynamic information. In an 
email task, the email can contain dynamic content in the list of recipients, the 
subject, and the message body. For more information, see "Add an Email Task" on 
page 60. 

The parts of a news item notification that can contain dynamic content are the 
headline, the screen tip, and the text. For more information, see "Add a News Item 
Task" on page 62. 

Although email and news item notifications can both show content dynamically, 
only email notifications can change their target dynamically. By inserting email 
address items in the recipient fields, you can specify that the recipient list change 
according to the data in the event list. 

Email Notifications 

You can notify people by e-mail using either a report task or an email task. To help 
you decide which method to use, you should understand how they differ. 

You can use either a report task or an email task 
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• to send a single email text message 

• to attach a single report in the specified output formats 

Note: If you attach only one HTML report and leave the body field empty, the 
report appears in the message body 

• to add links to a single report for the specified output formats 

For an e-mail task but not a report task, you can also 

• add dynamic content to the message, which may result in multiple emails 

This means that you can insert source items from a package into the message. If 
you insert an e-mail address item in the recipient fields, you can tailor the 
recipient list so that it is specific to the data in the message. 

• send multiple reports in a single email as attachments, links, or both 

For example, you can attach a report about stock usage and a report on 
unfulfilled customer orders when a particular stock item falls below a reorder 
level. 

• attach the event list 

Emailing reports from an IBM Cognos Event Studio agent is useful if you want the 
report to be tailored to a specific event. However, if you want to regularly send a 
report by email that is not related to an event, you do not need to create an agent. 
You can send it by email from IBM Cognos Connection. For more information, see 
the IBM Cognos Connection User Guide. 

News Item Notifications 

A news item task publishes a headline to a folder whose contents can be viewed in 
an IBM Cognos Navigator portlet and in any folder view. When someone clicks on 
a headline, they can open IBM Cognos Business Intelligence content or view a web 
page. 

How Multiple Events Affect E-mail Messages, Approval 
Requests, and Notification Requests 

When you create an e-mail message, approval request or notification request, you 
can drag data items into the recipient, subject, and message body fields. These data 
items act as placeholders. When the agent runs, the placeholders are replaced with 
actual values from the data source. 

If data items appear only in the message body, a single message is usually sent 
containing details of all the events detected. If the recipient or subject fields 
include data items, many e-mails or requests may be sent. 

For an example that illustrates the effect of multiple events, see "Add an Email 
Task" on page 60. 

Dynamic Address 

For some e-mails or requests, the appropriate recipient depends on the values in 
the event. For example, an e-mail about a support call from Customer A must be 
addressed to Customer A's account manager. 

If the data source includes an item that represents e-mail addresses, you can drag 
this item to the recipient fields. The agent uses this data to generate the e-mail 
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address dynamically. If the agent detects several events that satisfy the event 
condition, it generates one message or request for each e-mail address. The source 
items in the message body are grouped by address. 

Dynamic Subject 

If you include a source item in the subject field, the agent generates one message 
or request for each subject. The source items in the message body are grouped by 
subject. 

Dynamic Address and Dynamic Subject 

If you include source items in both the address and subject fields, the messages or 
requests are grouped by address and subject. 

Dynamic Message Body 

If an agent detects several events that satisfy the event condition, the size of the 
message body in the delivered message or request can increase. Every line that 
contains a data item placeholder is repeated for each event instance that satisfies 
the task execution rules. 



The Sample Outdoors Company 

The Sample Outdoors Company samples illustrate product features and technical 
and business best practices. 

You can also use them for experimenting with and sharing report design 
techniques and for troubleshooting. As you use the samples, you can connect to 
features in the product. 

For examples related to different kinds of businesses, see the product blueprints on 
the IBM Cognos Information Centers (http:/ /publib.boulder.ibm.com/infocenter/ 
cogic / vlrOmO /index, jsp) . 

For information about audit samples, see the IBM Cognos Business Intelligence 
Administration and Security Guide. 

For information about Mobile samples, see the IBM Cognos Mobile Installation and 
Administration Guide. 

The Sample Outdoors Company, or GO Sales, or any variation of the Sample 
Outdoors name, is the name of a fictitious business operation whose sample data is 
used to develop sample applications for IBM and IBM customers. Its fictitious 
records include sample data for sales transactions, product distribution, finance, 
and human resources. Any resemblance to actual names, addresses, contact 
numbers, or transaction values, is coincidental. Unauthorized duplication is 
prohibited. 

Where to find the samples 

The samples are included with the product and the samples for each studio are 
described in the related user guide and online help. To use the samples, you must 
install, set up, and configure them or contact your administrator to find out where 
they are installed. 
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For instructions on how to install the samples, see the IBM Cognos Business 
Intelligence Installation and Configuration Guide. For instructions on how to set up 
and configure samples, see the IBM Cognos Business Intelligence Administration and 
Security Guide or the IBM Cognos Business Intelligence Installation and Configuration 
Guide. 

Samples outline 

The samples consist of the following: 

• Two databases that contain all corporate data, and the related sample models for 
query and analysis 

• Five samples cubes and the related models 

• A metrics data source including associated metrics and a strategy map for the 
consolidated company, and a model for Metric extracts. 

• Reports, queries, query templates, and workspaces 

To run interactive reports, scripts are required. To see all the reports included in 
the samples packages, copy the files from the samples content installation into 
deployment folder and then import the deployments into the IBM Cognos 
Business Intelligence product. 

Security 

Samples are available to all users. 

To implement security, see the IBM Cognos Business Intelligence Installation and 
Configuration Guide. 



IBM Cognos Event Studio Samples 

IBM Cognos Business Intelligence includes report samples and an agent sample. 
When installed, you can find them in the Public Folders tab in IBM Cognos 
Connection, under GO Sales (Query), in the IBM Cognos Event Studio Samples 
folder. 

The Customer Contact Sample 

This report sample is used in a tutorial in this document. 

For more information, see Chapter 4, "Tutorial - Creating an Agent," on page 55. 

The Returns Agent Sample 

This agent sample was created using the IBM Cognos Event Studio example 
illustrated in IBM Cognos Business Intelligence Getting Started. If you try this 
example yourself, you can compare the agent that you create with the Returns 
Agent sample. 

The Returns Agent sample notifies you when a customer returns a product 
because it was defective, unsatisfactory, or incomplete, or because the wrong 
product was shipped. 
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The ELM Returns Agent Sample 

This agent sample is used in the topic "Example - Managing the Life Cycle of an 
Event." 

The ELM Returns Agent sample notifies you when a customer returns a product 
because it was defective, unsatisfactory, or incomplete, or because the wrong 
product was shipped. Two days after detecting the event, this agents checks if the 
issue is resolved. If unresolved event instances still exist, it runs the ELM 

Escalation Agent sample. 

The ELM Escalation Agent Sample 

This agent sample is used in the topic "Example - Managing the Life Cycle of an 
Event." 

The ELM Escalation Agent sample is run by the ELM Returns Agent sample. If 
more than two days have lapsed since the ELM Returns Agent sample detected an 
event, the ELM Escalation Agent sample escalates the issue by sending an e-mail 
to the customer fulfilment manager. 



Example - Managing the Life Cycle of an Event 

Try this example to see how the ELM Returns Agent sample performs different 
tasks depending on the stage of the life cycle for the event. 

Event Life cycle Management (ELM) is the ability to identify, track, and take 
appropriate action on an event at the right time and in the right sequence. 
Different information, people, and tasks are required at different stages in the life 
cycle of an event. 

You are the customer fulfilment manager for a company. After analyzing data 
warehouse metrics, you determine that when orders are returned for reasons that 
your company can control, there is a significant impact on customer loyalty. 
Customers withhold payment for the entire order until the issue is resolved. 

To identify these issues and resolve them as quickly as possible, you decide to run 
the ELM Returns Agent sample. To run this agent, do the following: 

• Perform setup tasks that are necessary only to demonstrate this example. These 
tasks are as follows: 

- Configure your mail server so that IBM Cognos Business Intelligence can 
send notifications. 

- Modify the agent samples to send e-mails to you. 

- Simulate the occurrence of initial events. 

- Simulate the passage of time and the resolution of some events. 

• Preview the output of all agent tasks. 

• Detect initial events and act on them as necessary. 

• Detect an ongoing, unresolved event and escalate the issue. 

• Confirm that the ELM Escalation Agent sample completed all its tasks 
successfully 
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Example - Configure Your Mail Server 

Configure your IBM Cognos Business Intelligence mail server to send notifications 
using IBM Cognos Event Studio or IBM Cognos Connection. 

Procedure 

1 . Start IBM Cognos Configuration. 

2. In the Explorer pane, click Notification. 

3. Enter the notification properties: 

• In the SMTP mail server box, type a mail server that is appropriate for your 
environment. 

• In the Account and Password box, type your e-mail user ID and password. 

• In the Default sender box, type the following: 
notifications@ibmcognos 

4. Save the configuration. 

Example - Modify the Agent Samples to Send E-mails to You 

The IBM Cognos Event Studio agent samples named ELM Returns Agent and 
ELM Escalation Agent are set up to send e-mails to other people. 



To view the e-mails that these other people would normally receive, change the 
recipient e-mail address to your own e-mail address. 

Modify the ELM Returns Agent Sample 

Use the following steps for the ELM Returns Agent sample. 



Procedure 

1 . Start IBM Cognos Connection. 

2. Click GO Sales (Query). 

3. Click Event Studio Samples. 



4. Click the Event Studio button on the actions toolbar next to the ELM 
Returns Agent sample. 

Event Studio starts, and the ELM Returns Agent sample appears. 

5. Near the top of the window, click the Follow up required e-mail task. 

6. In the Specify the email to send window, in the To box, replace 
salesrepresentative@yourcompany.com with your own e-mail address. 

7. From the File menu, click Save. 

8. From the File menu, click Exit. 



Results 



The destination address is changed to your e-mail address so that the agent sends 
e-mails to you. The sender address remains notifications@ibmcognos. 

Modify the ELM Escalation Agent Sample 

Use the following steps for the ELM Returns Agent sample. 



Procedure 



1 . 



In IBM Cognos Connection, click the Event Studio button 
toolbar next to the ELM Escalation Agent sample. 




on the actions 
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Event Studio starts, and the ELM Escalation Agent sample appears. 

2. Near the top of the window, click the Outstanding Returned Item Order 
e-mail task. 

3. In the Specify the email to send window, in the To box, replace 
FulfilmentManager@yourcompany.com with your own e-mail address. 

4. From the File menu, click Save. 

5. From the File menu, click Exit. 

Results 

The destination address is changed to your e-mail address so that the agent sends 
e-mails to you. The sender address remains notifications@ibmcognos. 

Example - Simulate the Occurrence of Initial Events 

Run part of the IBM Cognos Event_Studio_ELM_Agent_Modify_GoSales.sql script 
to simulate data changes. 

The following data changes can be simulated: 

• change the date to the current date 

• change the follow-up code to -1 in four records 
A code of -1 indicates that follow-up is required. 

Procedure 

1 . In SQL Query Analyzer, from the File menu, click Open. 

2. Go to c'l OJocation / webcon ten t/sa tuples / d a tasou rces / sqlserver and double-click 
the Event_Studio_ELM_Agent_Modify_GoSales.sql file. 

3. In the toolbar, from the list of databases, click gosales. 

4. In the Query window, under Part 1, select all sixteen lines of code. 

5. From the Query menu, click Execute. 

Results 

The database is updated with the changes. 

Example - Preview the Output of Each Task of an Agent 

You can preview the output of the IBM Cognos Event Studio ELM Returns Agent 
sample based on the current data, without running the agent. 

Procedure 

1 . In IBM Cognos Connection, click the Event Studio button on the actions 
toolbar next to the ELM Returns Agent sample. 

Event Studio starts, and the ELM Returns Agent appears. 

2. From the Actions menu, click Preview All. 

Results 

A window appears that shows the event list and the output that would be 
produced by each agent task. Based on this preview information, you can decide 
whether to run the agent. 
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Example - Detect Initial Events and Act on Them 

Run the IBM Cognos Event Studio ELM Returns Agent to detect the initial 
instances of products returned for specific reasons. 



When these events are detected, the ELM Returns Agent does the following: 

• It runs the AssignStaff stored procedure. 

AssignStaff provides details about the sales representatives associated with each 
event instance, including the e-mail address. 

• It sends an e-mail to the appropriate sales representatives, advising them to 
contact their customer. 

• It runs the ELM Escalation Agent. 

The ELM Escalation Agent checks for returned product events flagged by the 
ELM Returns Agent. If one of these events still exists after two days, the ELM 
Escalation Agent sends an e-mail to the customer fulfilment manager. 



Procedure 

1 . In IBM Cognos Connection, click Public Folders, then click GO Sales (query), 
and then click Event Studio Samples. 



2 . 

3. 

4. 

5. 

6 . 



on the actions toolbar next to the ELM 



Click the run with options button . 

Returns Agent sample. 

Under Time, click Now. 

Under Prompt values, clear the Prompt for values check box. 
Click Run. 

Click OK. 



Results 



You receive two e-mails, originally intended for sales representatives Karen 
Bowman and Clarice Oliveira. The e-mail to Karen Bowman notifies her of one 
returned order. The e-mail to Clarice Oliveira notifies her of the three returned 
orders assigned to her. 

The task execution rules for the ELM Returns Agent sample specify that all tasks 
are performed for new events only. If you do not receive any e-mails, the agent 
may already have run, so that none of the detected events are new. You can reset 
the event list so that when the agent runs next, all detected events have a status of 
new. 

Tip: From the Actions menu, click Reset Event List. 

Example - Simulate the Passage of Time and the Resolution of 
Some Events 

Run part of the Event_Studio_ELM_Agent_Modify_GOSALES.sql script to simulate 
data changes. 

First, change it so that two days elapsed since the ELM Returns Agent sample was 
last run. Second, for three of the four event instances found the last time that the 
ELM Returns Agent sample ran, change the follow-up code from -1 to +1. This 
indicates that only one of the these event instances still requires follow-up and the 
other instances are resolved. 
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Procedure 

1 . In SQL Query Analyzer, from the File menu, click Open. 

2. Go to clOJoozfz'on/webcontent/samples/datasources/sqlserver and double-click 
the Event_Studio_ELM_Agent_Modify_GOSALES.sql file. 

3. On the toolbar, click GOSALES from the list of databases. 

4. In the Query window, under Part 2, select all lines of code that appear after the 
comments. 

5. From the Query menu, click Execute. 

Results 



The database is updated with the changes. 



Example - Detect an Ongoing Unresolved Event and Escalate 
the Issue 

Run the IBM Cognos Event Studio ELM Returns Agent sample a second time. The 
agent now detects only one event because you modified the follow-up codes in the 
previous task. In addition, because two days lapsed since the sales representative 
was notified, the event condition of the ELM Escalation Agent sample is met. The 
ELM Escalation Agent sample detects the event and sends an e-mail to the 
customer fulfilment manager. 



Procedure 

1 . In IBM Cognos Connection, click Public Folders, then click GO Sales (query), 
and then click Event Studio Samples. 



2 . 

3. 

4. 

5. 

6 . 



On the actions toolbar, click the run with options button 
Returns Agent sample. 

Under Time, click Now. 

Under Prompt values, clear the Prompt for values check box. 
Click Run. 

Click OK twice. 



next to the ELM 



Results 



After this agent runs, you receive only one e-mail. Instead of being sent to the 
sales representative, this issue is escalated to the customer fulfilment manager. 



Example - Confirm that the ELM Escalation Agent Sample 
Completed Its Tasks Successfully 

Using IBM Cognos Connection, you can confirm that the IBM Cognos Event Studio 
ELM Escalation Agent sample, which is run by the ELM Returns Agent sample, 
completed its tasks successfully. 



Procedure 

1 . In IBM Cognos Connection, click Public Folders, then click GO Sales (query), 
and then click Event Studio Samples. 

2. On the actions toolbar next to the ELM Escalation Agent sample, click More. 

3. Click View run history. 

4. In the Actions column, click the view run history details button . 



20 IBM Cognos Event Studio Version 10.2.0: User Guide 




Results 



A window appears showing that the event query and e-mail task succeeded. 
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Chapter 3. Creating an Agent 

Create an agent to monitor data for instances of an event and to perform tasks. 

Before you begin 

Before you create an agent, you should understand the notification methods that 
an agent can use. You should also know how often an agent performs different 
types of tasks. 

To create an agent, do the following: 

• Specify the event condition. 

• Add one or more of the following types of tasks for the agent to perform when 
the event status meets the task execution rules: 

- e-mail task 

- news item task 

- report task 

- job task 

- agent task 

- approval request task 

- notification request task 

- database update task 

- web service task 

- export task 

- import task 

- content maintenance task 

- metric task 

- planning macro task 

- migration task 

• Specify the task execution rules. 

After you create an agent, you can: 

• preview it 

• test it 

• run it 

• work with it in IBM Cognos Connection 

• modify the event condition 

• modify a task 

• modify the task execution rules 
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Specify an Event Condition 

When you specify an event condition, you describe a specific occurrence of data 
items that an agent must detect before it performs its tasks. The event condition is 
a query expression that you create using items from the package. 

For more information, see "Specify an Event Condition" on page 57. 

Before you begin 



If you want to include parameters or calculations in the event condition, you must 
create them before you define the event. 



Procedure 



1. 

2 . 



3. 



From the Actions menu, click Specify Event Condition 




Create a detail expression, a summary expression, or both: 

• If you want part of the event condition to apply to values of individual 
source items, click the Detail tab and follow step 3. 

• If you want part of the event condition to apply to aggregate values, click 
the Summary tab and follow step 3. 



In the Expression box, create a query expression: 

• Drag items from the source tab or type text directly. 

• Drag operators, summaries, and other mathematical functions from the 
functions tab or type text directly. 

Tip: To see the meaning of an icon on the functions tab, click the icon and 
read the description in the Information box. 

• If you want to insert a parameter, drag it from the parameters tab. 

• If you want to insert a calculation, drag it from the data items tab. 

• Insert values if required. 



Tip: To select from a list of possible values for the selected item, click the 



select value button 



_| 



Move the values you want from the Select Value 



box to the Selected Items box and click OK. 



For example, you can type the following expression: 

[Unit price] * [Quantity sol d] > 5000 

4. To check the event list to ensure that you specified the event condition 
correctly, from the Actions menu, click Preview. 

5. To determine how many event instances there are, from the Actions menu, 
click Count Events. 



6 . 

7. 



From the File menu, click Save As 




Specify a name and location for the agent and click OK. 



Results 



You can preview the event list returned by the event condition. For more 
information, see "Preview the Data" on page 45. 
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Define a Parameter 

You can define a parameter and include it in an event condition. When the agent 
runs, it prompts the user to enter a value for the parameter. You can also use 
parameters to accept the results of a previous agent. 

For more information, see "Define a Parameter to Insert Into an Event Condition" 
on page 56. 

Procedure 

1 . From the Insert menu, click Parameter 

2. In the Parameter name box, type a name for the parameter. 

3. Click OK. 

The parameter appears in the data items tab. 

Results 




You can include the parameter when you specify an event condition. 

Define a Calculation 

A calculation is a query expression that defines an arithmetic combination of data 
items. For example, you can define a calculation named Product Sales that is the 
product of the unit price and the quantity sold. 



For more information, see "Define a Calculation to Insert Into an Event Condition" 
on page 57. 



Procedure 



1. 

2 . 
3. 



From the Insert menu, click Calculation 




In the Name box, type a name for the calculation. 

In the Expression box, define the calculation: 

• Drag items from the source tab or type text directly. 

Tip: If you type the text, you must include the full path of each data item. 
For example, you can type the following expression: 

[gosal es_goretai 1 ers] . [Orders] . [Uni t price] * 

[gosal es_goretai 1 ers] . [Orders] . [Quantity] 



• Drag operators, summaries, and other mathematical functions from the 
functions tab or type text directly. 

Tip: To see the meaning of an icon on the functions tab, click the icon and 
read the description in the Information box. 

• Insert values if required. 



Tip: To select from a list of possible values for the selected item, click the 



select value button 



H 



. Move the values you want from the Select Value 



box to the Selected Items box and click OK. 



4. Click OK. 



The calculation icon appears on the data items tab. 
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Results 



You can include the calculation when you specify an event condition or specify a 
task. 



Adding Tasks 

You can add multiple tasks to an agent. However, you can specify only one event 
condition per agent. Each task is performed for the event list that meets the 
execution rules you specify for the task. The agent performs tasks in the order that 
you add them, unless you change their order later. You can save an agent and add 
additional tasks to it later. 

You can add source items or data items to some types of tasks. When the agent 
performs the task, it uses the current value of the item. If you want the agent to 
use the value that a particular item had the previous time the agent ran, you can 
insert the previous function before the item. 

To insert the previous function, from the Insert menu, click Previous Value. 

Add an Email Task 

Add an email task to an agent to send an email about an event to specified 
recipients. You can include content, such as report output, in an email task. 

For more information, see "Add an Email Task" on page 60. 

You can also add other types of tasks. Email tasks share some similarities with 
report tasks. For more information, see "Email Notifications" on page 12. 

Before you begin 

Before you add any type of task, you must specify an event condition. 

Procedure 

1 . In the I want to area, click Add a task. 

2. Click Send an email. 

3. In the To box, and if applicable, in the Cc or Bcc boxes, enter the email 
addresses of the recipients using one or more of the following methods: 

• Type the addresses directly, separating each email address with a semicolon. 

• If your model contains a data item that is an email address, drag this item 
from the source tab or from the data items tab. When the agent runs, the 
current value in the package replaces the data item for each event instance. 

• Click Select the recipients. Select the users, groups, roles, contacts, and 
distribution lists. Select the entries you want, click the arrow button to 
update the Selected entries list, and click OK. 

4. In the Subject box, type the subject of the email. 

Tip: You can also drag items from the source tab or from the data items tab. 
When the agent runs, the current value in the package replaces the data item 
for each event instance. 

5. In the Body box, type the email message text directly or drag items from the 
source tab or from the data items tab. 

If you insert data items in the Body box, the body message will be longer. 
When the agent runs, the current value in the package replaces the data item 
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for each event instance. For more information, see "How Multiple Events 
Affect E-mail Messages, Approval Requests, and Notification Requests" on 
page 13. 

If the email has a single HTML attachment and the Body box is empty, the 
attachment appears inline. 

6. To change the message format from HTML to plain text or vice versa: 

• To change from the default HTML format to plain text format, click Change 
to plain text. 



Note: If you switch to plain text format, any HTML formatting changes are 
lost. 

• To change from plain text to HTML, click Change to HTML format. You 
can then use formatting buttons to edit the message. 

7. To add attachments, click Attach and choose the attachments. 

8. To add links, click Add links, select the entries you want, click the arrow 
button to update the Selected entries list, and click OK. 

9. Under Run this email for the events, review the event status that will cause 
the email to be sent. 

Tip: If you want to change this event status, you can edit the task execution 
rules. 



1 0. From the File menu, click Save 



H 



Results 



You can preview the email task. When the agent runs, it retrieves values for all 
source and data items and sends the email to the recipients you chose. 

Add a News Item Task 

Add a news item task to an agent to publish a headline to a folder in IBM Cognos 
Connection. 

For more information, see "Add a News Item Task" on page 62. 

You can also add other types of tasks. 

Before you begin 

Before you add any type of task, you must specify an event condition. 

Procedure 

1 . In Cognos Connection, create a new folder or portlet. 

For more information, see the IBM Cognos Connection User Guide. 

2. In IBM Cognos Event Studio, specify an event condition. 

3. In the I want to area, click Add a task. 

4. Click Publish a news item. 

5. In the Headline box, type the text you want to appear at the top of your news 
item. 

Tip: You can also drag items from the source tab or the data items tab. 

6. To add a description in the Screen tip box and in the Text box, type a 
description of the entry. 
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The screen tip is limited to 100 characters. 

Tip: You can also drag items from the source tab or from the data items tab. 

7. Under Link to, choose an object to appear when you click a news headline: 

• To link to IBM Cognos Business Intelligence content, click Select an entry, 
go to the entry, and click OK. For example, if you want the Customer 
Contact report to appear when someone clicks the headline, click Select an 
entry, locate the Customer Contact report, and click OK. 

Tip: You can add a report task that runs a report before the news item task 
is performed. If you link that report to the news item task, the report 
always shows information about current event instances when someone 
clicks the headline. 

• To link to a URL, type the URL address in the box. 

If the URL points to a web site address, include the protocol, such as http. 
For example, to create a URL for the IBM web site, you would type 
http:/ /www.ibm.com. 

8. Under News list location, click Select a location, go to the folder or portlet in 
which the news item will be published and click OK. 

9. Under Publish this news item for the events, review the event status that 
will cause the news item to be published. 

Tip: If you want to change this event status, you can modify the task 
execution rules. 



1 0. From the File menu, click Save 



a 



Results 



You can preview the news item task. When the agent performs the news item task, 
it publishes the news headline to the location you chose. When you click the 
headline, the Cognos BI entry or the web page you linked to appears. 

The description text appears when you set your Cognos Connection preferences to 
use the details view. The screen tip appears when you pause your pointer over the 
icon for the entry in the news list location. 

Add a Report Task 

Add a report task to an agent to run a report that is related to an event. 

For more information, see "Add a Report Task" on page 58. 

You can also add other types of tasks. Email tasks share some similarities with 
report tasks. For more information, see "Email Notifications" on page 12. 

Before you begin 

Before you add any type of task, you must specify an event condition. 

You must have permissions to run the report that you select. For more information, 
see the IBM Cognos Report Studio User Guide. 

Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run a report. 
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3. In the Select the Report dialog box, specify the report, query, analysis, or 
report view to include in the agent. 

• Search the folders to find the entry you want. 

• Click the entry and click OK. 

4. To customize the report, under Options, click Set and make the necessary 
changes. 

5. If the report includes parameters, under Prompt values, choose how to specify 
prompt values for each parameter: 

• If you are using an item, in the Method column, click Use an item and drag 
an item from the source tab or from the data items tab to the Value column. 

Tip: When you specify a data item, values from the event list are passed as 
prompt values in the report. If the event list has multiple instances, then 
multiple values are passed as prompt values. Therefore, you must ensure 
that the report being run has a prompt that can accept multiple values. For 
more information, see the IBM Cognos Report Studio User Guide. 

• If you are using a value, in the Method column, click Use a value, click 
Specify values, and in the Value column, type a value. 

Tip: If you want to clear the prompt values and return to the default values, 
click Reset to default. 

6. Under Run this report for the events, review the event status that will cause 
the report to run. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



7. 



From the File menu, click Save 




Results 



You can preview the report task. When the agent performs the report task, it runs 
the report and delivers it according to the delivery options you chose. 

Customize the Report 

You can change the report options from the defaults to customize the report for 
your audience. 

The following are the options you can change: 

• Change one or more report output formats. 

• Change one or more languages. 

• Change one or more delivery methods. 

• Burst the report if it was authored with bursting specifications. 

Default options are set by the report author. You can change some default run 
options for reports. 

You change the report options when you click Set or Edit in the Specify the report 
to run dialog box. For more information, see "Add a Report Task" on page 28. 

Setting the report options for a report task in IBM Cognos Event Studio is similar 
to running a report with options in IBM Cognos Connection. For more information, 
see the IBM Cognos Connection User Guide. 
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Procedure 

1 . In the Select the report options dialog box, select the Override the default 
values check box. 

2. Under Formats, click the formats you want for the report output. 

3. To select different or additional languages for the report, click Select the 
languages and use the arrow keys to move the available languages to the 

Selected languages box and click OK. 

Tip: To select multiple languages, press Ctrl+click or Shift+click. 

4. Under Delivery, choose a delivery method: 

• To save the report, select the Save check box, then click the button next to 

Save the report. 

• To save the report as a report view, select the Save check box, then click the 
button next to Save the report as a report view. You can change the name or 
target folder of the report view by clicking Edit the options. Make the 
changes, and click OK. 

Tip: Save the report as a report view if you do not have write access to the 
report. You can then add a link to the report view when you specify an 
e-mail task. 

• To print the report, select the Print the report check box and click Select a 
printer. Click the button next to the printer you want to use and click OK. 
Or, if the printer is not listed, you can type the printer information. 

Tip: If you have administrator privileges and want to set up the printer for 
future use, click New printer. You must type the network address of the 
printer by using the format Wserver _name\pr inter _name for a network printer 
on a Windows operating system installation and printer _name for a UNIX 
operating system installation or for a local printer. 

• To e-mail the report, select the Send the report by email check box. 

5. If you clicked Send the report by email, click Edit the options to specify what 
you want: 

• To send the e-mail to IBM Cognos Business Intelligence recipients, click 
Select the recipients. Select the check box next to the names you want to 
include, and click To, Cc (copy), or Bcc (blind copy). The entries that you 
select are listed under Selected entries. Click OK. 

Tip: To select all entries in a list, click the check box in the upper-left corner 
of the list. To remove names from Selected entries, select the check box next 
to the name and click Remove. To search, click Search. In the Search string 
box, type the phrase you want to search for. For advanced search features, 
click Advanced. 

• If you want to send the e-mail to other recipients, in the To:, Cc, or Bcc 
boxes, type the email addresses separated by semicolons (;). 

Tip: If you logged on, your name automatically appears in the To list box. 

• Under Subject, type the subject of the e-mail. 

• Under Body, type a message to be included in the e-mail. 

• If you want to include an attachment, select the check box to include the 
report or a link to the report, and click OK. 

If you are an administrator, you can prevent users from including 
attachments. For more information, see the IBM Cognos Administration and 
Security Guide. 

6. Under Bursting, specify whether the report should be bursted. 
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This option is available only if the report author defined burst keys in the 
report. 

7. Click OK. 

The Specify the report to run dialog box appears. 

8. Continue specifying the report. For more information, see "Add a Report Task" 
on page 28. 

Add a Job Task 

Add a job task to an agent to run a job. A job identifies a collection of reports, 
report views, agents, and other jobs that are scheduled together and share the 
same schedule settings. 

For more information, see the IBM Cognos Connection User Guide. 

For example, in IBM Cognos Connection, you create a job named Two Reports, and 
select two reports that you want the job to run. In IBM Cognos Event Studio, you 
add a job task and select the Two Reports job. When the agent runs and detects 
events that meet the task execution rules, it runs the Two Reports job. 

You can also add other types of tasks. 

Before you begin 



Before you add any type of task, you must specify an event condition. 



Before you create a job task, you must create a job in Cognos Connection. For more 
information, see the IBM Cognos Connection User Guide. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run a job. 

3. In the Select the job dialog box, specify the job to include in the agent. 

• Search the folders to find the job you want. 

• Click the entry and click OK. 

4. Under Run this job for the events, review the event status that will cause the 
job to run. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



5. From the File menu, click Save 



a 



Results 



You can preview the job task. When the agent performs the job task, it runs all the 
IBM Cognos Business Intelligence items identified in the job. 

Add an Agent Task 

Add an agent task to an agent to run another agent. By running multiple agents in 
sequence, you can use the output from one agent as the input to another agent. 
You can also use multiple agents that interact with each other using data retrieved 
from different data sources. This removes the need to join databases using IBM 
Cognos Framework Manager. 
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For more information, see "Example - Adding an Agent Task." 
You can also add other types of tasks. 

Before you begin 



Before you add any type of task, you must specify an event condition. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run an agent. 

3. In the Select the agent dialog box, choose an agent. 

• Search the folders to find the agent you want. 

• Click the entry and click OK. 

4. If the task includes parameters, under Prompt values, choose how to specify 
prompt values for each parameter: 

• If you are using a value, in the Method column, click Use a value, click 
Specify values, and in the Value column, type a value. 

• If you are using an item, in the Method column, click Use an item and drag 



an item from the source tab 
Value column. 




or from the data items tab 




to the 



Tip: If you want to clear the prompt values and return to the default values, 
click Reset to default. 



5. Under Run this agent for the events, review the event status that will cause 
the agent to be run. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



6. From the File menu, click Save 



H 



Results 



You can preview the agent task. When the agent performs the agent task, it runs 
the agent you specified. 

Example - Adding an Agent Task 

You want to run the high_retums_followup agent to detect a high rate of returned 
items and resolve the related issue. However, for each item that has a high rate of 
return, you also want to check the importance of the customer to your company as 
calculated from data in a data warehouse system. The customer's importance value 
is calculated using projected sales and profit data. 

You create a second agent named high_returns_customer_check that is run by the 
high_returns_followup agent. When a high return event occurs, the 
high_returns_followup agent runs and passes customer details to the 
high_returns_customer_check agent. The high_returns_customer_check agent then 
runs a query to check the customer importance value. If the customer importance 
value is high, the high_returns_customer_check agent sends an e-mail asking the 
customer services agent to contact the customer and fix the problem immediately. 
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Add an Approval Request Task 

Add an approval request task to an agent when you want an event to occur only 
after approval. This task sends an approval request related to an event to the task 
inbox of specified recipients in IBM Cognos Business Intelligence. 

For more information on the task inbox, see the IBM Cognos Connection User 
Guide. 

A recipient can be a potential owner or a stakeholder. Multiple users, groups, roles, 
and distribution lists can be assigned as potential owners of an approval request 
task. Stakeholders can be users, groups, roles, and distribution lists that are 
identified as interested parties, but are not potential owners. 

Tip: To track the progress of an approval request task that you create, you can add 
yourself as a stakeholder. 

You can include content, such as report output, in an approval request. 

You can set up approval requests with different actions: 

• Approve/Reject the request 

The task owner must approve or reject the request from their task inbox to 
complete the task. If you schedule further agent tasks to run after the approval 
request task, these are dependent on approval by the task owner. If the request 
is rejected, no further agent tasks will run. 

• Specify which of the remaining tasks to run 

When you schedule further agent tasks to run after the approval request, the 
task owner must select which of those tasks to run on completion of the 
approval request. 

You can add start date and due date deadlines to an approval request when you 
create the task in IBM Cognos Event Studio. Alternatively, potential owners or 
stakeholders can add deadlines at a later date by updating the approval request 
from their task inbox. 

You can set up notification options for e-mails to be sent to 

• all potential owners when an approval request is created 

• the task owner when an approval request is not completed by the due date 

• the task owner when an approval request is not started by the start date 

Note: Stakeholders are also copied on e-mails. 

In addition, you can set up notification options for the task owner and all 
stakeholders to receive emails when 

• the status of an approval request changes (started, completed or canceled) 

• the owner of an approval request changes 

• a comment is added to an approval request 

Note: Potential owners and stakeholders can unsubscribe from receiving specific 
notifications by updating the approval request from their task inbox. 

You can add customized icons, using your own graphic files, to approval requests 
that appear in a recipient's task inbox. 
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To add a customized icon, use one of the following methods: 

• Type the explicit location and name for the graphic file. 

• Insert an item from the Insertable Items pane that contains a value for the 
relative path and name for the graphic file. 

Files to support custom icons must be located within the cl 0_location \ webcon ten t 
directory and a copy of the files must exist on all Cognos Business Intelligence 
gateway server installs. 

For example, to use the file green.jpg, where Cognos Business Intelligence is 
installed in c:\program files\IBM\cognos\clO\, green.jpg must exist within a path 
contained within c:\program files\IBM\cognos\clO\webcontent\ 

When you configure a task to use green.jpg (located in c:\program 
files\IBM\cognos\clO\webcontent\samples\images\) as a customized icon, the 
value you enter in the icon Item box is either 

• ./samples/images/green.jpg (explicit location) 

• or, an item from the insertable items pane which contains the value 
./samples/images/green.jpg (relative location) 

You can also add other types of tasks. 

Procedure 

1 . Specify an event condition which always returns the value True. For example 
" 1 = 1 ". 

For more information, see "Specify an Event Condition" on page 24. 

2. In the I want to area, click Add a task. 

3. Click Run an approval request. 

4. In the Potential owners box, and if applicable, in the Stakeholders box, enter 
the names of the recipients by using one or more of the following methods: 

• If your model contains a data item that is a user, group, role or distribution 
list, drag this item from the source tab or from the data items tab. When 
the agent runs, the current value in the package replaces the data item for 
each event instance. 

• Click Select the recipients to select the users, groups, roles or distribution 
lists. 

To choose from listed entries, click the appropriate namespace, and then 
select the required check boxes. 

Tip: To make the user entries visible, click Show users in the list. 

To search for entries, click Search and in the Search string box, type the 
phrase you want to search for. For search options, click Edit. Find and click 
the entry you want. 

Click the Potential Owner or Stakeholder arrow button to update the 
Selected entries list, and click OK. 

Tip: To remove entries from the Selected entries list, select them and click 
Remove. To select all entries in a list, click the check box in the upper-left 
corner of the list. 

Click OK. 

Note: You must add at least one stakeholder. By default, you are added as a 
stakeholder when you create the approval request. 
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5. In the Subject box, type the subject of the approval request. 

Tip: You can also drag items from the source tab or from the data items tab. 
When the agent runs, the current value in the package replaces the data item 
for each event instance. 

6. In the Body box, type text directly or drag items from the source tab or from 
the data items tab. 

If you insert data items, the body message will be longer. When the agent 
runs, the current value in the package replaces the data item for each event 
instance. For more information, see "How Multiple Events Affect E-mail 
Messages, Approval Requests, and Notification Requests" on page 13. 

7. To change the message format: 

• Click Change to plain text to change from the default HTML format to 
plain text format. 

Note: If you switch to plain text format, any HTML formatting changes are 
lost. 

• Click Change to HTML format to change from plain text to HTML. You can 
then use formatting buttons to edit the message. 

8. To add attachments, click Attach and choose the attachments. 

9. To add links, click Add links, select the entries you want, click the arrow 
button to update the Selected entries list, and click OK. 

1 0. Select the following due date options if required: 

• Start within to add a start by deadline, and then type the number of days 
in the Days box. 

• Due within to add a due date deadline, and then type the number of days 
in the Days box. 

11. To add a customized icon to the approval request in the task inbox, drag an 
item from the source tab or from the data items tab into the icon Item box. 
Tip: To revert to using the default task icon, select the Default icon option. 

12. To change the priority of the approval request, select a predefined option from 
the Priority list or drag an item from the source tab or from the data items 
tab into the priority Item box. 

1 3. Select the action required by the task owner to complete the task: 

• Approve/Reject the running of all remaining tasks (default) 

By default, the approval request contains Approve and Reject action 
buttons. To change the default button names, click Customize, type the 
required names, and then click OK. 

• Specify which of the remaining tasks to run 
Select the tasks to include in the approval request. 

Note: Only agent tasks that are scheduled to run after the approval request 
are listed here. 

By default, the approval request contains a Submit action button. To change 
the default button name, click Customize, and type the required button 
name. When you have finished, click OK. 

Tip: You can also change the names of the agent tasks as they appear in the 
task inbox. For example, you could append the task type to the agent task 
name. 

1 4. Select the approval request creation and deadline notification options as 
required: 



Chapter 3. Creating an Agent 35 



• Send notification upon creation (default) 

• Send notification if not started by start by date 

• Send notification if not completed by due date 

1 5. Select the approval request change notification options as required: 

• Started 

• Comment 

• Owner changed 

• Completed 

• Canceled 

1 6. From the File menu, click Save HI. 

Results 

You can preview the approval request task. When the agent runs, it retrieves 
values for all source and data items and sends the approval request to the 
recipients you specified. 

Add a Notification Request Task 

Add a notification request task to an agent to send a secure notification about an 
event to the task inbox of specified recipients in IBM Cognos Business Intelligence. 

For more information on the task inbox, see the IBM Cognos Connection User 
Guide. 

A notification request can have various recipients: 

• users, groups, roles, and distribution lists to whom the request is sent (To list 
recipients) 

• stakeholders to whom the request is copied (CC list recipients) 

Tip: To track the progress of a notification request task that you create, you can 
add yourself as a copied (CC) recipient (stakeholder). 

You can include content, such as report output, in a notification request. 

You can set up the following notification options: 

• Request an acknowledgement from each recipient included on the To list, with 
an optional deadline date. 

• All recipients receive an email when a notification request is added to their task 
inbox. 

• Recipients included on the To list receive an email if they have not 
acknowledged a notification request by the deadline date. 

• Stakeholders included on the CC list receive an email on the deadline date 
informing them that some recipients on the To list have not acknowledged the 
notification request. 

You can also add other types of tasks. 

Procedure 

1 . Specify an event condition which always returns the value True. For example 
" 1 = 1 ". 
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For more information, see "Specify an Event Condition" on page 24. 

2. In the I want to area, click Add a task. 

3. Click Run a notification request. 

4. In the To box, and if applicable, in the Cc box, enter the names of the 
recipients by using one or more of the following methods: 

• If your model contains a data item that is a user, role or group, drag this 
item from the source tab or from the data items tab. When the agent runs, 
the current value in the package replaces the data item for each event 
instance. 

• Click Select the recipients to select the users, groups, roles or distribution 
lists. 

To choose from listed entries, click the appropriate namespace, and then 
select the required check boxes. 

Tip: To make the user entries visible, click Show users in the list. 

To search for entries, click Search and in the Search string box, type the 
phrase you want to search for. For search options, click Edit. Find and click 
the entry you want. 

Click the To or Cc arrow button to update the Selected entries list, and 
click OK. 

Tip: To remove entries from the Selected entries list, select them and click 
Remove. To select all entries in a list, click the check box in the upper-left 
comer of the list. 

Click OK. 

5. In the Subject box, type the subject of the notification request. 

Tip: You can also drag items from the source tab or from the data items tab. 
When the agent runs, the current value in the package replaces the data item 
for each event instance. 

6. In the Body box, type text directly or drag items from the source tab or from 
the data items tab. 

If you insert data items, the body message will be longer. When the agent 
runs, the current value in the package replaces the data item for each event 
instance. For more information, see "How Multiple Events Affect E-mail 
Messages, Approval Requests, and Notification Requests" on page 13. 

If the notification request has a single HTML attachment and the Body box is 
empty, the attachment appears inline. 

7. To change the message format: 

• Click Change to plain text to change from the default HTML format to 
plain text format. 

Note: If you switch to plain text format, any HTML formatting changes are 
lost. 

• Click Change to HTML format to change from plain text to HTML. You can 
then use formatting buttons to edit the message. 

8. To add attachments, click Attach and choose the attachments. 

9. To add links, click Add links, select the entries you want, click the arrow 
button to update the Selected entries list, and click OK. 

1 0. To change the priority, select a predefined option from the Priority list or drag 
an item from the source tab or from the data items tab into the Item box. 

1 1 . Select the notification request notification options as required: 
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• Send notification by email upon creation 

• Request acknowledgement 

• Send notification if not acknowledged within 

Type the specified number of days in the Days box. 



12 . 



From the File menu, click Save 




Results 



You can preview the notification request task. When the agent runs, it retrieves 
values for all source and data items and sends the notification request to the 
recipients you specified. 

Add a Database Update Task 

Add a database update task to an agent to run stored procedures that exist in a 
database. A stored procedure takes arguments as input and updates the database. 
The database that contains the stored procedures can be different from the 
database in the package that the agent is monitoring. 

For information about running stored procedures, see the IBM Cognos 
Administration and Security Guide. 

You can also add other types of tasks. 

A stored procedure is accessible in IBM Cognos Event Studio only if it was marked 
as a data modification type in IBM Cognos Framework Manager. If the input 
parameters to the stored procedure task are unavailable, check how your 
procedure has been modelled. For more information, see the IBM Cognos 
Framework Manager User Guide. 

Before you begin 



Before you add any type of task, you must specify an event condition. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Update a database. 

3. Under Package, select the package to use to update the database. 

4. Under Data modification stored procedure, select a stored procedure that 
exists for the package you selected. 

5. If the stored procedure includes arguments, under Arguments, choose how to 
specify values for each argument: 



• If you are using a value, in the Method column, click Use a value, click 
Specify values, and in the Value column, type a value. 



• If you are using an item, in the Method column, click Use an item and drag 



an item from the source tab 
Value column. 




or from the data items tab 




to the 



Tip: To clear the argument values and return to the default values, click Reset 
to default. 



6. Under Update the database for the events, review the event status that will 
cause the stored procedures to run. 
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Tip: If you want to change this event status, you can modify the task execution 
rules. 



7. From the File menu, click Save 



H 



Results 



You can preview the database update task. When the agent performs the database 
update task, the stored procedures are run and the database is updated. 

Add a Web Service Task 

Use a web service task to trigger an external process. Web services let software 
programs interact with one another using standard Internet protocols, so 
interaction is not dependant on operating system or program language 
compatibility. Web services also work well in a distributed environment because 
they use URLs to reference programs. 

You can also add other types of tasks. 

Before you begin 



Before you add any type of task, you must specify an event condition. 

When you specify the web service URL, IBM Cognos Event Studio calls a web 
server and requests the Web Services Description Language (WSDL). This shows 
you the web service input and output parameters. 



Note: Before you can run a web service task in Cognos Event Studio, you must 
follow additional preparation steps. For more information, see "Preparing to Run a 
Web Service Task" on page 50. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Advanced. 

3. Click Call a Web service. 

4. In the Web service URL box, type the URL of the web service. 

If the URL points to a web site address, you must include the protocol, such as 
http. 

5. Click Retrieve. 

The available web service operations are retrieved. 

6. Under Operation, click the web service operation you want to perform. 

The available method and the list of arguments is retrieved. 

7. If the operation includes arguments, under Arguments, choose how to specify 
values for each argument: 

• If you are using a value, in the Method column, click Use a value, click 
Specify values, and in the Value column, type a value. 

• If you are using an item, in the Method column, click Use an item and drag 



an item from the source tab 
Value column. 




or from the data items tab 




to the 



Tip: To clear the argument values and return to the default values, click Reset 
to default. 
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8. Under Call the Web service for the events, review the event status that calls 
the web service. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



9. From the File menu, click Save 



H 



Results 



You can preview the web service task. When the agent performs the web service 
task, it calls the web service and runs its service. 

Example - Adding a Web Service Task 

You want to notify customer service representatives and suppliers about orders 
that have a high rate of return. You could do this by adding an e-mail task. 
However, you know that some of the service representatives and suppliers do not 
have access to e-mail. You also know that they all closely monitor the Customer 
Relationship Management (CRM) system. 

You decide to notify the service representatives and suppliers by creating records 
in the CRM system. Each record is linked to a customer name and to the type of 
product that was returned. Your company developed a web service that creates 
CRM records. In IBM Cognos Event Studio, you add a web service task that calls 
your company's web service. 

When the agent performs the web service task, the web service updates the profile 
of customers who returned products. An updated customer profile can improve 
your sales performance in two ways: 

• It helps the services representative contact the customer quickly to resolve the 
current problem. 

• It helps the supplier ensure that they don't make the mistake of supplying a 
particular product to that customer again. 

Add an Export Task 

Add an export task to an agent to export entries to a deployment archive. The 
export is defined in IBM Cognos Connection. 

For more information, see the IBM Cognos Administration and Security Guide. 

You can also add other types of tasks. 

Before you begin 

Before you add any type of task, you must specify an event condition. 

Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run an export. 

3. Click Select the export, and specify the export to include in the agent. 

• Search the folders to find the export you want. 

• Click the entry and click OK. 

4. Under Run the export for the events, review the event status that runs the 
export. 
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Tip: If you want to change this event status, you can modify the task execution 
rules. 



5. From the File menu, click Save 



H 



Results 



You can preview the export task. 

Add an Import Task 

Add an import task to an agent to import entries from a deployment archive to 
your target environment. The import is defined in IBM Cognos Connection. 

For more information, see the IBM Cognos Administration and Security Guide. 

You can also add other types of tasks. 

Before you begin 



Before you add any type of task, you must specify an event condition. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run an import. 

3. Click Select the import and specify the import to include in the agent. 

• Search the folders to find the import you want. 

• Click the entry and click OK. 

4. Under Run the import for the events, review the event status that will run the 
import. 

Tip: To change this event status, you can modify the task execution rules. 



5. 



From the File menu, click Save 




Results 



You can preview the import task. 

Add a Content Maintenance Task 

Add a content maintenance task to an agent to run a content maintenance task 
created in IBM Cognos Connection. A content maintenance task searches the 
content store for user information that no longer exists in your external 
namespaces. It can also fix the content store by deleting any users that do not exist 
in your external namespaces. 

For more information, see the IBM Cognos Administration and Security Guide 
You can also add other types of tasks. 

Before you begin 

Before you add any type of task, you must specify an event condition. 
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Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run a content maintenance task. 

3. Click Select the content maintenance task and specify the content maintenance 
task to include in the agent. 

• Search the folders to find the content maintenance task you want. 

• Click the entry and click OK. 

4. Under Run the content maintenance task for the events, review the event 
status that runs the content maintenance task. 



5. 



6 . 



Tip: To change this event status, you can modify the task execution rules. 
Under Mode, choose whether to find or find and fix problems: 

• To find user information that no longer exists in your external namespaces, 
click Find only. 

• To find and delete from the content store any users that do not exist in your 
external namespaces, click Find and fix. 



From the File menu, click Save 



H 



Results 



You can preview the content maintenance task. 

Add a Metric Task 

Add a metric task to an agent to run tasks that are available in a metric package. 
For example, you can clear metric history data from the data store or you can 
import data from files into a staging area. 

For more information, see the IBM Cognos Metric Studio User Guide. 

You can also add other types of tasks. 

Before you begin 



Before you can open a metric package, you must install IBM Cognos Metrics 
Manager. For more information, see the IBM Cognos Metrics Manager Quick Start 
Installation and Configuration Guide. Before you add any type of task, you must 
specify an event condition. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Metric Task. 

3. Click Select the metric task and specify the metric task to include in the agent. 

• Search the folders to find the metric task you want. 

• Click the entry and click OK. 

4. Under Run the metric task for the events, review the event status that runs the 
metric task. 

Tip: To change this event status, you can modify the task execution rules. 



5. From the File menu, click Save 



3 
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Results 



You can preview the metric task. 

Add a Planning Macro Task 

Add a planning macro task to an agent to run Contributor macros when specified 
conditions are met. A planning macro is created in IBM Cognos Planning 
Contributor to automate tasks such as loading import data and publishing data. 

For more information about planning macros, see the IBM Cognos Planning 
Contributor Administration Guide. 



You can also add other types of tasks. 

Before you begin 



Before you add any type of task, you must specify an event condition. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Advanced. 

3. Click Run a planning macro task. 

4. Click Select the planning macro and specify the task to include in the agent. 

• Search the folders to find the task you want. 

• Click the entry and click OK. 

5. Under Run the planning macro task for the events, review the event status 
that runs the task. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



6. From the File menu, click Save 



H 



Results 



You can preview the task. 

Add a Migration Task 

Add a migration task to an agent to migrate IBM Cognos Series 7 PowerPlay® 
content to IBM Cognos PowerPlay. The migration task must be defined in IBM 
Cognos Administration. 

For more information on defining a migration task, see the IBM Cognos PowerPlay 
Migration and Administration Guide. 

You can also add other types of tasks. 

Before you begin 

Before you add any type of task, you must specify an event condition. 
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Procedure 

1 . In the I want to area, click Add a task. 

2. Click Advanced. 

3. Click Run a migration task. 

4. Click Select the migration task and specify the task to include in the agent. 

• Search the folders to find the task you want. 

• Click the entry and click OK. 

5. Under Run the migration task for the events, review the event status that runs 
the task. 

Tip: If you want to change this event status, you can modify the task execution 
rules. 



6. From the File menu, click Save 



H 



Results 



You can preview the task. 



Specify the Task Execution Rules 

Task execution rules specify when a task is performed. By default, a task is 
performed for new instances of events and all ongoing instances of events, but you 
can change this. 

For more information, see "Change the Task Execution Rules for a Report Task" on 
page 59 or "Change the Task Execution Rules for an Email Task" on page 62. 

You specify the task execution rules separately for each task in the agent. 

Before you begin 



Before you specify the task execution rules, you must add one or more tasks. 



Procedure 



1. 

2 . 



In the I want to area, click Manage the task execution rules 




On the Event Key tab, click one of the following: 

• Include all items (default) 



Include only selected items, then on the source tab 



13 



click one or more 



data items that uniquely define an event and drag it to the box. 



For example, click Order Number, because no two event instances can have 
the same order number. 



The event key is defined for all tasks in the agent. 

3. Click the Event Selection tab. 

4. In the Task box, click the task that the agent will perform for the event statuses 
you specify. 

5. Under Select when to perform each task page, click one of the following: 

• For selected events, and select one or more event status values. 

• When the agent or any of its tasks fail. 

6. Click OK. 
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The execution rules for each task you selected are set. 

Tip: If you want to reset the execution rules for every task in the agent to the 
default values, from the Actions menu, click Remove Task Execution Rules. 
Each task is reset to be performed for new instances of events and all ongoing 
instances of events. 

7. Save the agent. 



Preview the Data 

You can see the list of events detected when the event definition is applied to the 
current data. You can also see preview information about each task in your agent. 

For example, you are an administrator and want to preview the event list and all 
the tasks before you make the agent available for other people to use. 

The preview information for each type of agent item is described in the following 
table. 



Agent item 


Preview information 


The event list 


A table appears with columns for each data item contained in the event 
condition. For each event instance, a row appears that shows the value 
of each data item. 


e-mail task 


Representations appear of all e-mails that would be sent using the 
default task execution rules. Data items in the recipient, subject, and 
body fields are replaced by values from the source data. 


News item task 


A representation appears of the news item that would be created using 
the default task execution rules. Data items in the recipient, subject, and 
body fields are replaced by values from the source data. 


Report task 


If the report accepts prompt values, a table appears with columns for 
each parameter. For each event instance, a row appears that contains the 
prompt values. 

If the report does not accept prompt values, a sentence appears telling 
you that the report will run once. 


Job task 


A sentence appears telling you that the task will run once. 


Agent task 


If the agent accepts prompt values, a table appears with columns for 
each parameter. For each event instance, a row appears that contains the 
prompt values. 

If the agent does not accept prompt values, a sentence appears telling 
you that the agent will run once. 


Approval request 
task 


A representation appears of the approval request that would be created 
using the default task execution rules. Data items in the recipient, 
subject, and body fields are replaced by values from the source data. 

In addition, a table appears indicating the approval request deadlines, 
priority, and action button names. 


Notification 
request task 


A representation appears of the notification request that would be 
created using the default task execution rules. Data items in the 
recipient, subject, and body fields are replaced by values from the 
source data. 

In addition, a table appears indicating the priority and notification 
request options. 
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Agent item 


Preview information 


Database update 
task 


If the stored procedure accepts arguments, a table appears with 
columns for each argument. For each event instance, a row appears that 
contains the argument values. 

If the stored procedure does not accept arguments, a sentence appears 
telling you that the stored procedure will run once. 


Web service task 


If the web service accepts arguments, a table appears with columns for 
each argument. For each event instance, a row appears that contains the 
argument values. 

If the web service does not accept arguments, a sentence appears telling 
you that the web service will run once. 


Export task 


A sentence appears telling you that the task will run once. 


Import task 


A sentence appears telling you that the task will run once. 


Content 

maintenance task 


A sentence appears telling you that the task will run once. 


Metric task 


A sentence appears telling you that the task will run once. 


Planning macro 
task 


A sentence appears telling you that the task will run once. 


Migration task 


A sentence appears telling you that the task will run once. 



Items shown on the preview pages show data for every event instance in the event 
list. If you change the task execution rules, the preview data remains the same. For 
more information, see "Specify the Task Execution Rules" on page 44. 

Before you begin 

Before you can preview data, you must define an event condition. 

Procedure 

From the Actions menu, click Preview All or Preview. 

Results 

The Preview All report begins with a table of contents that contains links to the 
preview information for each agent item. The Preview report shows preview 
information for the agent item on the current page. 



Create a Schedule for an Agent 

By scheduling an agent to run at regular intervals, you do not have to manually 
run the agent. The agent monitors data and performs tasks to ensure that problems 
are dealt with as soon as possible. 

You use IBM Cognos Connection to schedule an agent the same way that you 
schedule other IBM Cognos Business Intelligence items. For more information, see 
the IBM Cognos Connection User Guide. 

Only one schedule can be associated with each agent. If you require multiple 
schedules for an agent, create agent views and then create a schedule for each 
view. 
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Procedure 

1 . In the I want to area, click Schedule the agent. 

2. Under Frequency, select how often you want the schedule to run. 

3. Under Start, select the date and time when you want the schedule to start. 

4. Under End, select when you want the schedule to end. 

Tip: If you want to create the schedule but not apply it right away, select the 
Disable the schedule check box. To later enable the schedule, clear the check 
box. 

5. If you want to override the default values that you defined for the agent, under 
Prompt values, select the check box. 

6. Click OK. 

Specify Default Options for an Agent 

Specify default options for an agent when you want every task in the agent to use 
the same values for report task options or content maintenance options. 

Procedure 

1 . From the Actions menu, click Set Default Options for All Tasks. 

2. Specify the default options you want. 

3. From the File menu, click Save H . 

Results 

In IBM Cognos Connection, you can change the defaults that are set for agents in 
IBM Cognos Event Studio, such as whether to use prompt values and run the 
agent as owner. For more information, see the IBM Cognos Connection User Guide. 



Allow Users to Subscribe to the Alert List of the Agent 

You can specify that you want IBM Cognos Connection users to be able to add 
their e-mail addresses to the agent alert list. 

When the agent runs, the alert list is added to the Bcc box in all e-mails sent using 
e-mail tasks or report tasks. 

For information about how to add your name to an alert list, see the IBM Cognos 
Connection User Guide. 



Procedure 

1 . From the Actions menu, click Manage Alert List. 

2. Select the Allow users to add themselves to the alert list check box. 



Tip: If you want to remove everyone from the alert list, click Remove all. 
3. From the File menu, click Save 



y 
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Change the Order in Which to Run Tasks 

You can change the order in which to run tasks. By default, all tasks run at the 
same time. These are called parallel tasks. If some tasks require a significant 
amount of processing time, parallel tasks can save time. 

You can also specify that one task finishes before the next task begins, and so on. 

For example, an agent runs a report task that saves a prompted report. Next, the 
agent runs an e-mail task and attaches the saved report. For more information, see 
Chapter 4, "Tutorial - Creating an Agent," on page 55. 

Note: If your agent contains any of the following tasks, and the task includes a 
saved report from a report task, you must order the tasks in a particular way: 

• email task 

• approval request task 

• notification request task 



You must order the e-mail task or request task after the report task. If you do not 
order the tasks in this way, the saved report output or report link will be missing 
from the e-mail or request that is created. 



Procedure 



□. 



1 . In the I want to area, click Reorder the tasks I 

2. Choose whether to specify the order or run all tasks at the same time: 

• To run the tasks in a specific order, click In sequence and, in the Tasks box, 
click tasks and change their order by clicking Up or Down. 

• To run all the tasks in parallel, click All at once. 

3. Click OK. 



4. From the File menu, click Save 



y 



Modify an Event Condition 

Modify an event condition when you want to change the data instances that 
prompt the agent to perform its tasks. 



Procedure 



1. 

2 . 

3. 

4. 



In IBM Cognos Connection, click the edit agent button 
want to modify. 

In the summary area, click the Event tab. 



for the agent you 



Change the values as required. For more information about the values required 
for an event condition, see "Specify an Event Condition" on page 24. 



From the File menu, click Save 




Modify or Delete a Task 

Modify or delete a task when you want to make changes to any of the tasks in the 
agent. 
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If you want to add a task, in the I want to area, click Add a task, and click a task 
type. For more information, see "Adding Tasks" on page 26. 

Procedure 



1. 

2 . 



3. 



In IBM Cognos Connection, click the edit agent button 
want to modify. 

If you want to modify a task, do the following: 



for the agent you 



In the summary area, under Tasks, click the tab for the task you want. 



• Change the values as required. For more information about the values 
required for each type of task, see "Adding Tasks" on page 26. 

If you want to delete a task, do the following: 

• In the summary area, under Tasks, click the tab for the task you want to 
delete. 



• From the Edit menu, click Delete 




4. Save the agent. 



Modify the Task Execution Rules 

Modify the task execution rules when you want to change the list of event 
instances for which a task is performed. 



Procedure 



1. 

2 . 

3. 

4. 



In IBM Cognos Connection, click the edit agent button |®j for the agent you 
want to modify. 

In the I want to area, click Manage the task execution rules. 



Change the values as required. For more information, see "Specify the Task 
Execution Rules" on page 44. 



If you want to reset the task execution rules to the default values, from the 
Actions menu, click Remove Task Execution Rules. 



The task is performed for new instances of events and all ongoing instances of 
events. 



5. From the File menu, click Save 



H 



Test an Agent 

Before you run an agent, you can test whether certain conditions are met to 
increase the chance that the agent runs successfully. 

The conditions are as follows: 

• The event condition is a valid query expression. 

• All parameters are satisfied correctly. 

• All referenced data items exist. 

Procedure 

1 . From the Actions menu, click Validate . 

The View the validation results dialog box appears. 

2. If an error message appears, fix the error and then repeat steps 1 to 2. 
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If an error message appears when you run the agent, write down the error 
message and troubleshoot the problem. 

For more information, see the Troubleshooting section of the IBM Cognos 
Business Intelligence Administration and Security Guide. 

3. When the No Errors message appears, click OK. 

Results 

The agent is now ready to run. 



Preparing to Run a Web Service Task 

Before you can run a web service task in IBM Cognos Event Studio, you must 
generate the required Java object (.jar) file for the web service and register the 
domain name for the web service. 

Generating a Java Object File 

When you generate Java object (.jar) files, the folder c!0_Zocotion\webapps\p2pd\ 
WEB-INFM i b\es_ws_objs is created automatically, and files are stored here by 
default. 

If you are an administrator, you can change this folder using IBM Cognos 
Configuration. 

To generate .jar files, you must be running Java Development Kit (JDK) with a Java 
compiler (javac.exe). 

Note: If you are running multiple web services, you must generate a separate .jar 
file for each one. Because each generated file has the same file name, you must 
rename each .jar file before generating the next one. 

Procedure 

1 . On a Windows operating system, open the file clO_location\b\ n\ 
es_bui 1 d_ws_obj s . bat in an XML editor. 

On non Windows operating systems, open the file clO_location\ bi n\ 
es_bui 1 d_ws_obj s . sh in an XML editor. 

2. Modify the JAVA_HOME environment variable to point a JDK location. 

3. Run the following command from the clO_location\b\n location: 

On a Windows operating system, type 

es_bui 1 d_ws_obj s <web_servi ce_URL> 

For example, es_build_ws_objs http:/ /wtwincqclab7/ws6/service.asmx?wsdl 
On non Windows operating systems, type 
. / es_bui 1 d_ws_obj s . sh <web_servi ce_URL> 

This command generates a file named es_ws_objs.jar in the specified location. 
The following steps are optional, and only required if you want to change the 
default location for your Java object files. 

4. Start IBM Cognos Configuration. 

5. In the Explorer window, click Local Configuration. 

6. In the Properties window, next to Advanced properties, click inside the Value 
box, and then click the edit button. 

7. Click Add, and then type the following property name in the Name box: 
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emf . webservi ce . obj s . f ol der 



Note: You must create this folder manually in your directory structure. 

8. In the Value box, type the required folder location. 

Note: The location must be accessible to the server user. 

9. Click OK, and save your changes. 

1 0. Restart the services. 

Registering the Domain Name 

You must register the domain name for the web service in the IBM Cognos 
Application Firewall (CAF) using IBM Cognos Configuration. 

Procedure 

1 . Start Cognos Configuration. 

2. In the Explorer window, under Security, click IBM Cognos Application 
Firewall. 

3. Add host and domain name to the Cognos list of valid names: 

• For the Valid domains and hosts property, click the value and then click the 
edit button. 

• In the Value - Valid domains or hosts dialog box, click Add. 

• In the blank row of the table, click and then type the host or domain name. 

4. Click OK, and save your changes. 

5. Restart the services. 



Run an Agent 

You can run an agent in IBM Cognos Connection when you want to check for 
event instances and perform tasks if those events occur. 

For example, an agent is created to send an email to sales staff in a particular 
region when they reach 75 percent of their sales quota for the month. The agent 
prompts for the sales region. A sales manager specifies Spain, and emails are sent 
only to sales staff in Spain. 

Run an agent manually if you do not want to wait until it runs according to a 
schedule. 



Before you begin 



You must have execute, write and traverse permissions to run an agent. You must 
have traverse permissions for the folder that contains the agent. 



If you want to ensure that every event instance is assigned a status of new when 
the agent runs, remove previous event instances by resetting the event list. 



Procedure 

1 . In Cognos Connection, in Public Folders or My Folders, click the run with 



options button on the actions toolbar next to the agent you want to run. 



2. Under Time, click Now or click Eater to specify a later date and time. 
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3. If you want the agent to prompt for values and filter the results it retrieves, 
under Prompt Values, select the Prompt for values check box. 

4. Click Run. 

You are prompted for values if the agent includes prompts or if you have 
access to multiple data source connections or signons. 

5. If prompts appear, respond appropriately. 

6. Click OK. 

The options that you specified override the default agent options only for the 
current run. 

Results 

You can view the run history of the agent in Cognos Connection. For more 
information, see the IBM Cognos Connection User Guide. 

Remove Previous Event Instances for an Agent 

If you want to ensure that every event instance is assigned a status of new the next 
time that an agent runs, remove previous event instances by resetting the event 
list. 

You may want to reset the event list if you edit the event condition such that it no 
longer makes sense to compare the current event list with the previous one. 
Resetting the event list can also help you to test the behavior of the agent when it 
detects new items. 

Before you begin 

Before you can reset the event list, you must define an event condition. You must 
also run the agent at least once. 

Procedure 

To remove previous event instances for an agent, from the Actions menu click 

Reset event list. 



Working With Agents in IBM Cognos Connection 

You can continue to work with agents in IBM Cognos Connection. 

You can view the run history of the agent, which shows when the agent ran and 
whether it ran successfully. If it did not run successfully, you can resubmit it. 

You can create an agent view if you want to share the agent with another user. You 
can apply different properties to the agent view, such as prompt values. You can 
also run the agent as an owner. If you want to change the properties of an agent 
and do not need to retain an agent with the original properties, you can simply 
change the default agent properties. 

You can make a copy of the agent if you want to use the copy as the basis for a 
new agent. 

You can create a shortcut if you want the agent to appear in more than one 
location. 
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You can add yourself to the alert list for the agent. When you subscribe to an alert 
list, you receive an email notification when the agent is run. 

For more information, see the IBM Cognos Connection User Guide. 
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Chapter 4. Tutorial - Creating an Agent 



This tutorial shows how the various tasks in creating an agent are related to each 
other. It shows that managing task execution rules is performed for each task in an 
agent, but that specifying an event condition is performed once for an agent. 

Scenario 

You are the Director of Sales of a company. The Finance department identified a 
problem with invoice payments. Analysis of warehouse data shows that a large 
proportion of late payments are by customers who returned damaged or faulty 
items and did not receive replacements. 

Customers tend to withhold payment for the entire order even if only one or two 
items are in dispute. They may even refuse to pay for other completed orders until 
the disputed order is resolved. 

Therefore, rapid resolution of the returns issues has a direct effect on cash flow. 

The Director of Finance asks you to establish a process that closely monitors data 
for problems with high rates of return and takes immediate action to resolve any 
problem it detects. 

Solution 

You decide to use IBM Cognos Event Studio to detect event instances and notify 
the people who must quickly resolve the issue. 

You create an agent named high_returns_followup. The agent detects cases where 
the actual value of returned products is greater than the threshold value that the 
person running the agent defines. You include a parameter in the event condition 
to represent this threshold value. Initially, you concentrate on large return orders 
because they have the greatest effect on cash received. After you address problems 
with the largest returns, you monitor lower valued returns. 

To provide sales representatives with customer contact information, you decide to 
add a report task that runs the Customer Contact report. The sales representatives 
can then quickly call the retailer and try to resolve the issue. 

Before you can distribute the report, you require a sales manager to approve and 
sign it off as being accurate, so you decide to an approval request task. 

When you add the e-mail task to distribute the report, you specify that the e-mail 
message be in HTML format. When you edit an HTML message, you can click a 
button that inserts a table. You list return values by order number in the table. 
Then you attach to the e-mail message both the report that you saved in the report 
task and the event list that shows the event instances for which the agent 
performed its tasks. 

To create this example agent, perform the following tasks: 

• Start Cognos Event Studio and select the Go Sales (query) package. 

• Define a parameter named total_return_value_for_item. 

• Define a calculation named order_item_return_value_calc. 
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• Specify an event condition that contains the calculation and parameter. 

• Add a report task that saves a report customized with contact information for 
the retailers who returned the products. 

• Change the task execution rules for the report task. 

• Add an approval request task that sends the report to the sales manager for 
sign-off. 

• Add an e-mail task that sends an email to the sales representative for the 
returned product. Attached to the email is the approved report. 

• Change the task execution rules for the email task. 

• Add a news item task that publishes a dynamic headline that shows the current 
value of preventable returns. 

• Schedule the agent. 

• Save the agent. 

• Run the agent. 



Start IBM Cognos Event Studio 

You want to start IBM Cognos Event Studio and ensure that your agent uses a data 
package that it can monitor for the events you want and that it can use to perform 
tasks. 

You decide to use the Go Sales (query) package because it contains data items 
related to returned products, retailers, and order details. 

Procedure 

1 . In IBM Cognos Connection, from the Launch menu, click the Event Studio link 




2. In the Select a package window, click Go Sales (query). 

Cognos Event Studio opens in a new window. The data items you can use are 
listed in the Insertable Objects area. 

Tip: If you want to continue working in both Cognos Event Studio and Cognos 
Connection, you can keep both windows open. 



Define a Parameter to Insert Into an Event Condition 

You want to define a parameter named total_return_value that you can insert into 
an event condition. 

Procedure 

1 . From the Insert menu, click Parameter. 

2. In the Parameter name box, type 
total_return_value_for_item 

3. Click OK. 

Results 

Tip: To see the parameter, in the Insertable Objects area, click the parameters tab 
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Define a Calculation to Insert Into an Event Condition 



You want to define a calculation named total_return_value_calc that you can insert 
into an event condition. This calculation must determine the total value of each 
order returned. 

Procedure 

1 . From the Insert menu, click Calculation. 

2. In the Name box, type 
order_item_return_value_calc 

3. In the Expression box, do the following: 

• In the Insertable Objects area, click the functions tab and expand 
Summaries. 

• Click the total function item, and drag it to the Expression box. 

• In the Insertable Objects area, click the source tab and expand Returned 
items (query). 

• Under Returned items (query), expand Returned items. 

• Click the Return quantity measure item, and drag it to the Expression box. 

• After you insert the source item, type for. 

• Under Returned items (query), expand Order. 

• Click the Order number item, and drag it to the end of the expression. 

• After you insert the source item, type a closing parenthesis. 

The calculation expression is defined as follows: 

total([Returned items (query)]. [Returned items]. [Return quantity] for [Returned 
items (query)]. [Order], [Order number]) 

4. Click OK. 

Results 



The calculation appears as a calculation icon 




on the data items tab. 



Specify an Event Condition 

You want the agent to detect cases where the actual value of returned products is 
greater than the threshold value that the person running the agent defines. 

Also, you want to see what parameter value would return an event list of between 
5 and 10 items from the current data. 



Procedure 

1 . Click the Detail tab. 



2 . 

3. 

4. 

5. 

6 . 



m 



In the Insertable Objects area, click the source tab 
Expand Returned items (query). 

Under Returned items (query), expand Returned items. 

Click the Return quantity measure item, and drag it into the expression box. 
After the source item you just inserted, type 
> 0 and 
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7 . 

8 . 



a 



On the data items tab LMJ , click the order_item_return_value_calc 
calculation that you defined previously, and drag it to the end of the 
expression. 

At the end of the expression, type a greater than symbol: 



> 



9. Click the parameters tab HHj , click the total_return_value parameter that you 
defined previously, and drag it to the end of the expression. 

10. At the end of the expression, type 

and 



1 1 . On the source tab, under Returned items (query), expand Return reason. 

1 2. Click Reason description, and drag it to the end of the expression. 

13. At the end of the expression, type 

in 



1 4. To include only the description types you want, do the following: 

• On the source tab, under Return reason, click Reason description. 

• Above the Expression box, click the select value button 

• In the Select Value window, use Shift+Click to select Incomplete product. 
Unsatisfactory product, and Defective product. 

• Click the insert button I I , and click OK. 

The detail expression appears as follows: 

[Return quantity] >0 and 

[order_item_return_value_calc]>?total_return_value_for_item? and [Reason 
description] in ('Defective prod net’, 'Incomplete product'/Unsatisfactory 
product') 

1 5. Do the following to see whether an event list of between 5 to 10 items is 
returned when the total return value calculation exceeds $4000: 

• From the Actions menu, click Preview. 

• On the report viewer Prompt pages, in the Provide a number box, type 
4000 

• Click OK. 




Add a Report Task 

Sales representatives must ensure that items returned for a preventable reason are 
not returned again for the same reason. You want to save a report of customer 
contact information associated with the excessive rate of return event that you 
defined. Sales representatives can use this information to contact the retailer, 
discuss how to prevent future returns, and then take the appropriate action. 

You decide to add a report task that runs the sample report named Customer 
Contact. When the agent runs the report task, the value of the Retailer name data 
item for each event instance is passed to the report output. 

By adding an email task, you can include additional information in the e-mail 
message that you cannot include using the report task. 
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Procedure 

1 . In the I want to area, click Add a task. 

2. Click Run a report. 

3. Specify the report that you want to run: 

• Click Public Folders, and click Go Sales (query). 

• Click Event Studio Samples. 

• Click Customer Contact Report and click OK. 

4. Under Options, click Set. 

5. Specify the run options that you want: 

• Select the Override the default values check box. 

• Under Formats, select the PDF check box and ensure that none of the other 
check boxes are selected. 

• Under Delivery, select the Save check box, and ensure that Save the report 
is selected. 

• Click OK. 

6. Specify the prompt values that you want: 

• In the Method column, click Use an item. 



7. 



• In the Insertable Objects area, click the source tab 
(query). Retailer. 

• Click Retailer name, and drag it to the Value box. 
Save the agent. 




and expand Sales 



Change the Task Execution Rules for a Report Task 

The status of each event instance is obtained by comparing the event instances of 
the current run of the agent to those of the previous run. You want to specify 
which event statuses will cause the agent to perform the report task. 

You know that for the event condition you specified, the Product name. Retailer 
name, and Order method data items have duplicate values in two or more event 
instances. However, because the Order number data item has a different value for 
each event instance, you choose it as the event key. 

You decide that the report task that you added previously should be performed for 
both: 

• new event instances 

New event instances are instances that are detected when the agent runs and 
were not previously detected. 

• ongoing event instances in which the return quantity has changed 

Ongoing event instances are detected when the agent runs and have previously 
been detected. In this case, only ongoing event instances in which the return 
quantity has changed cause the report task to run. 

Procedure 

1 . In the summary area, click new report. 

2. In the I want to area, click Manage the task execution rules. 

3. Click the Event Key tab. 

4. Click Include only selected items. 
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5. 

6 . 

7. 

8 . 

9. 

10 . 



On the source tab lOul , expand Returned items (query) and Order. 

Under Order, click Order number, and drag it to the Event key box. 

Click the Event Selection tab. 

Under Select when to perform each task, select the New events and Ongoing 
events check boxes. 

This chooses the event status for which the report task is performed. 

Click OK. 

Save the agent. 



Add an Approval Request Task 

You require a sales manager to approve the accuracy of the report that you saved 
previously and to sign it off before it is distributed to the sales representatives. 

You decide to add an approval request task. When the agent is run, a task will be 
created within My Inbox in IBM Cognos Business Intelligence and notifications will 
be sent via email to the potential owner and stakeholder identified for the task. 



For more information on approval request tasks, see "Add an Approval Request 
Task" on page 33. 



Note: When you add an approval request, the task execution is automatically set 
to sequential. 



Procedure 

1 . In the I want to area, click Run an approval request. 



2 . 

3. 

4. 



a 



, and expand Sales (query). 



Click the source tab 
Expand Sales Staff. 

Click Manager Email and drag it to the Potential owners box. 



Note: You are automatically added as a stakeholder of the task. 

5. In the Subject box, type 

Customer Contact Report for Approval 

6. In the Body box, type: 

Please approve or reject the content of the attached report. If you approve 
this report it will be distributed to 

7. To add the email distribution list for the sales representatives to the message: 

• Click the source tab, and expand Sales (query). 

• Expand Sales Staff. 

• Click Email and drag it to the end of your message. 

8. Save the agent. 



Add an Email Task 

When the Customer Contact report has been approved by the sales manager, you 
want to notify sales representatives about orders that have a high rate of return. 

You decide to add an email task. You specify that the e-mail message use HTML 
format. When you edit an HTML message, you can click a button that inserts a 
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table. You list return values by order number in a table. Then you attach to the 
email message both the report that you saved previously, and the event list 
showing the event instances for which the agent performed its tasks. 

Note: The email task will only execute if the approval request that you previously 
added is approved by the potential owner. 



Procedure 

1 . In the I want to area, click Add a task. 

2. Click Send an email. 



3. 

4. 

5. 

6 . 

7. 

8 . 



9. 



a 



, and expand Sales (query). 



Click the source tab 
Expand Sales Staff. 

Click Email and drag it to the To: box. 

In the Subject box, type 
Urgent: Please contact customer 
In the Body box, type: 

Please contact your customer about the following returned order(s), and 
determine how to prevent it from happening again 

Add a table to the Body message: 



• Click the insert table button 

• Type 4 in the Number of columns box, type 2 in the Number of rows box, 
and click OK. 

Type the column headings in the first row: 

• In the first cell, type 
Order Number 

• In the second cell, type 
Value of items returned 

• In the third cell, type 
Reason description 

• In the fourth cell, type 

Customer name (see attached contact information) 



1 0. Select the heading row, and click the bold button 

1 1 . Enter data items in the second row: 



• Click the source tab, expand Sales (query), then expand Order, and click 
Order number and drag it to the first cell. 



• Click the data items tab 

the second cell. 




, click total_return_value_calc, and drag it to 



• Click the source tab, expand Returned items (query), then expand Return 
reason, and click Reason description and drag it to the third cell. 

• Expand Sales (query), then expand Retailer site, and click Retailer name 
and drag it to the fourth cell. 

1 2. In the Body box, after the table, type 

Thanks, the GO Sales Customer Loyalty Team 

1 3. Click Attach, and click Attach the event output. 
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14. Click Attach, and click Attach the report Customer Contact. 

15. Save the agent. 

Change the Task Execution Rules for an Email Task 

The status of each event instance is obtained by comparing the event instances of 
the current run of the agent to those of the previous run. You want to specify 
which event statuses will cause the agent to perform the email task. 

You know that for the event condition you specified, the Product name. Retailer 
name, and Order method data items have duplicate values in two or more event 
instances. However, because the Order number data item has a different value for 
each event instance, you choose it as the event key. 

You decide that the email task you added previously should be performed only for 
event instances that did not appear in the event list the last time the agent was 
run. 

Tip: You can add multiple tasks to an agent and use task-level filters to include 
only those events that satisfy a Boolean condition. See "Example - Task-Level 
Boolean Filter" on page 10. 

Procedure 

1 . In the summary area, click new message. 

2. In the I want to area, click Manage the task execution rules. 

3. Under Select when to perform each task, select the New events check box and 
ensure that none of the other check boxes are selected. 

4. Click OK. 

5. Save the agent. 



Add a News Item Task 

The customer fulfilment manager wants to be informed of the current preventable 
returns. However, he does not always check his e-mail. He prefers to view 
important updates on a Web dashboard that he checks regularly. 



You decide to add a news item task that updates a headline with the total value of 
returns that are preventable. That is, you publish the values of products returned 
because they are incomplete, defective, or unsatisfactory. 



Procedure 

1 . Create a folder named High Returns. 



• In IBM Cognos Connection, click the new folder button 

• In the Name box, type 
High Returns 

• Under Location, click Select My Folders. 

• Click Finish. 




The High Returns folder [3 appears in My Folders. 

2. In IBM Cognos Event Studio, in the I want to area, click Add a task. 

3. Click Publish a news Item. 
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4. In the Headline box, type Preventable Returns for Large Value Individual 
Items. 

5. Drag the calculation data item total_return_value_calc to the end of the text 
you just typed. 

6. Under Link to, choose what you want to link to: 

• Click Select an entry. 

• Click Public Folders, and click Go Sales (query). 

• Click Event Studio Samples. 

• Click Customer Contact Report and click OK. 

7. Under News list location, click Select a location, go to the High Returns 
folder in which the news item will be published and click OK. 

8. Under Run this news item for the events, review the event status that will 
cause the news item to be published. 

9. From the File menu, click Save. 

Results 

When the agent performs the news item task, it publishes the news item to the My 
Headlines folder. 

The description text appears when you set your IBM Cognos Connection 
preferences to use the details view. The screen tip appears when you pause your 
pointer over the icon for the entry in the news list location. 



Schedule an Agent 

When the excessive rate of return event you defined occurs, significant potential 
revenue has already been lost. Following up on returned products increases your 
shipping charges and administration fees. However, the most important impact of 
returned products is that they can reduce customer loyalty and decrease your 
future sales. Therefore, it is important that you respond quickly to an event 
instance as soon as it occurs. 

You decide that you can provide a timely response to event instances by 
monitoring the data hourly. You also decide that $17,000 is an appropriate 
threshold value for this initial schedule. 

Procedure 

1 . In the I want to area, click Schedule the agent. 

2. Under Frequency, click By Day, and ensure that the frequency is Every 1 
hour(s). 

3. Under Start, select tomorrow's date, and specify the time as 9:00 AM. 

4. Under End, click No end date. 

Tip: You can edit the schedule later if you want to add an end date. 

5. Under Prompt values, select the Override the default values check box, and 
then click Set. 

6. On the prompt page, in the Provide a number box, type 
17000 

7. Click OK twice. 
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Results 



A schedule is created and the high_returns_followup agent runs hourly, starting 
tomorrow at 9:00 a.m. 



Save an Agent 

You want to save the agent in My Folders. You also want to give the agent a 
meaningful name and description so that you can easily distinguish it from other 
agents. 

Procedure 

1 . From the File menu, click Save. 

2. If this is the first time you are saving the agent, in the Save As dialog box, 
describe the agent: 

• In the Name box, type 
high_returns_followup 

• In the description field, type 

This agent checks for orders that have a high value of returned products. It 
then sends a report by e-mail to the appropriate sales reps so that they can 
contact the retailers and prevent future returns. 

• Ensure that the Location is set to My Folders. 

• Click OK. 

Results 

The agent high_returns_followup appears in My Folders, next to an agent icon 




Run an Agent 

You decide to run the agent immediately to test the results. 

If you want to successfully run the agent described in this tutorial, you must first 
perform the tasks in all the other examples. For more information, see Chapter 4, 
"Tutorial - Creating an Agent," on page 55. 

Procedure 

1 . In IBM Cognos Connection, in My Folders, click the run with options button 

h 

on the actions toolbar next to the high_returns_followup agent. 

2. Under Time, click Now. 

3. Under Prompt Values, select the Prompt for values check box. 

4. Click Run. 

5. On the Prompt page, in the Provide a number box, type 
17000 

6. Click OK twice. 
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Results 



The high_returns_followup agent runs using the prompt value you entered. To see 
the results of the run, you can review the run history of the agent. For more 
information, see the IBM Cognos Connection User Guide. 
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Chapter 5. Troubleshooting 

This chapter describes some common problems you may encounter. 

You can find more troubleshooting topics in the Troubleshooting section of the IBM 
Cognos Administration and Security Guide. 



A Report Link in an Email Notification Does Not Work 

If a report link in an email notification does not work, the Gateway URI may not 
be configured correctly 

You must change the host name portion of the Gateway URI from localhost to 
either the IP address of the computer or the computer name. If the URL in the 
email contains localhost, remote users cannot open the report. 



The Page Cannot Be Found Error Appears for Reports 

When a report is distributed by email, no error message appears if the report 
output from the email link is not available. This can occur when the output is 
deleted or when the user does not have permissions to the report. Instead, the 
error The Page Cannot Be Found appears. 

You are unable to view the report output from the email link when Allow 
Anonymous Access is set to True and when the Anonymous user does not have 
access to the report output. 

When you run a secured report from an email link and when Allow Anonymous 
Access is set to True, a passport is automatically issued to the Anonymous user. 
The Anonymous user is not prompted to log on and is unable to view the report 
output. 



Metadata Change in Oracle Essbase Not Reflected in Reports and in 
the Studios 



When there is a metadata change on the Oracle Essbase server, the change is not 
immediately reflected in the metadata tree in the studios. In addition, when a 
report is run, the report does not pick up the republished changes. 

To view the new structure, you must restart the IBM Cognos Content Manager 
server. 



Errors When Running Web Service Tasks 

When running a Web service task, you might encounter errors. 

You must modify one the following files to add the ThreadStackSize (Xss) 
parameter: 

• bootstrap_win32.xml in the bin folder for a 32-bit installation 

• bootstrap_win64.xml in the bin64 folder for a 64-bit installation 

Adding this parameter prevents these errors: 
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CNC-ASV-0001 The Following Agent Service General Error Occurred: 
j ava . lang . StackOverf lo wError 

CNC-ASV-0007 An error occurred with the agent Web service task. 

Procedure 

1. Open the appropriate version of the c'l 0_location \bi n \bootstrap_vvi n.xm I file in 
an XML editor. 

2. Add the following text for the parameter (shown in bold) exactly as shown 
here: 



<condVal ue="Sun">-XX:NewSi ze=${di spatcherMaxMemoryBy4}m</param> 

<param condName="${java_vendor} " condVal ue="Sun">-XX 

<process name="catalina"> ...<param condName="${java_vendor}" 
condVal ue="Sun">-XX:MaxPermSize=512m</param>< 
param condName="${java_vendor}" 
condVal ue="IBM">-Xss512m</param> 

The maximum stack size (Xss) parameter is set to 512 MB to avoid an overflow 
exception error. 



68 IBM Cognos Event Studio Version 10.2.0: User Guide 



Notices 



This information was developed for products and services offered worldwide. 

IBM may not offer the products, services, or features discussed in this document in 
other countries. Consult your local IBM representative for information on the 
products and services currently available in your area. Any reference to an IBM 
product, program, or service is not intended to state or imply that only that IBM 
product, program, or service may be used. Any functionally equivalent product, 
program, or service that does not infringe any IBM intellectual property right may 
be used instead. However, it is the user's responsibility to evaluate and verify the 
operation of any non-IBM product, program, or service. This document may 
describe products, services, or features that are not included in the Program or 
license entitlement that you have purchased. 

IBM may have patents or pending patent applications covering subject matter 
described in this document. The furnishing of this document does not grant you 
any license to these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
North Castle Drive 
Armonk, NY 10504-1785 
U.S.A. 

For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 

Intellectual Property Licensing 
Legal and Intellectual Property Law 
IBM Japan Ltd. 

1623-14, Shimotsuruma, Yamato-shi 
Kanagawa 242-8502 Japan 

The following paragraph does not apply to the United Kingdom or any other 
country where such provisions are inconsistent with local law: INTERNATIONAL 
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" 
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR 
PURPOSE. Some states do not allow disclaimer of express or implied warranties in 
certain transactions, therefore, this statement may not apply to you. 

This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the publication. IBM may make improvements 
and/or changes in the product(s) and/or the program(s) described in this 
publication at any time without notice. 

Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any manner serve as an endorsement of those Web 
sites. The materials at those Web sites are not part of the materials for this IBM 
product and use of those Web sites is at your own risk. 
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IBM may use or distribute any of the information you supply in any way it 
believes appropriate without incurring any obligation to you. 

Licensees of this program who wish to have information about it for the purpose 
of enabling: (i) the exchange of information between independently created 
programs and other programs (including this one) and (ii) the mutual use of the 
information which has been exchanged, should contact: 

IBM Software Group 
Attention: Licensing 
3755 Riverside Dr 
Ottawa, ON K1V 1B7 
Canada 

Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 

The licensed program described in this document and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM International Program License Agreement or any equivalent agreement 
between us. 

Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments may 
vary significantly. Some measurements may have been made on development-level 
systems and there is no guarantee that these measurements will be the same on 
generally available systems. Furthermore, some measurements may have been 
estimated through extrapolation. Actual results may vary. Users of this document 
should verify the applicable data for their specific environment. 

Information concerning non-IBM products was obtained from the suppliers of 
those products, their published announcements or other publicly available sources. 
IBM has not tested those products and cannot confirm the accuracy of 
performance, compatibility or any other claims related to non-IBM products. 
Questions on the capabilities of non-IBM products should be addressed to the 
suppliers of those products. 

All statements regarding IBM's future direction or intent are subject to change or 
withdrawal without notice, and represent goals and objectives only. 

This information contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 

If you are viewing this information softcopy, the photographs and color 
illustrations may not appear. 
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Trademarks 



IBM, the IBM logo, ibm.com, PowerPlay, and Cognos are trademarks or registered 
trademarks of International Business Machines Corp., registered in many 
jurisdictions worldwide. Other product and service names might be trademarks of 
IBM or other companies. A current list of IBM trademarks is available on the Web 
at " Copyright and trademark information " at www.ibm.com/legal/ 
copytrade.shtml. 

The following terms are trademarks or registered trademarks of other companies: 

• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of 
Microsoft Corporation in the United States, other countries, or both. 

• UNIX is a registered trademark of The Open Group in the United States and 
other countries. 

• Java and all Java-based trademarks and logos are trademarks or registered 
trademarks of Oracle and/or its affiliates. 

Microsoft product screen shot(s) used with permission from Microsoft. 




Java 
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Glossary 

This glossary includes terms and definitions for 
IBM Cognos Business Intelligence. 

The following cross-references are used in this 
glossary: 

• See refers you from a term to a preferred 
synonym, or from an acronym or abbreviation 
to the defined full form. 

• See also refers you to a related or contrasting 
term. 

To view glossaries for other IBM products, go to 
www.ibm.com / software / globalization / 
terminology (opens in new window). 

"A" "B" "C" "D" on page 75 "E" on page 75 "F" 
on page 75 "G" on page 75 "H" on page 76 "I" 
on page 76 "J" on page 76 "L" on page 76 "M" 
on page 76 "N" on page 77 "O" on page 77 "P" 
on page 77 "Q" on page 78 "R" on page 78 "S" 
on page 79 "T" on page 79 "U" on page 79 "W" 
on page 80 



A 

access permission 

A privilege that permits the access or use 
of an object. 

accountability scorecard 

A scorecard that Metric Studio 
automatically builds for each user which 
contains the metrics and projects they 
own. 

agent A process that performs an action on 

behalf of a user or other program without 
user intervention or on a regular 
schedule, and reports the results back to 
the user or program. 

alias An alternative name used instead of a 
primary name. 

anonymous access 

A type of access that allows users and 
servers to access a server without first 
authenticating with it. 

application tier component 

For installation, the set of processors that 
access the query databases to gather 
information and then render the results as 



PDF and HTML reports and metrics. 
Application tier components also pass 
requests to Content Manager and render 
the results that Content Manager retrieves 
from the content store. 

attribute 

In BI Modeling, a characteristic of an 
entity which is descriptive rather than a 
unique identifier or an aggregative 
measure. 

authentication 

The process of validating the identity of a 
user or server. 

authentication provider 

The communication mechanism to an 
external authentication source. 
Functionalities, such as user 
authentication, group membership, and 
namespace searches, are made available 
through authentication providers. 



burst To create several report results by running 
a single report once. For example, the 
user can create a report that shows sales 
for each employee, and run it once, 
sending different results to regional 
managers by bursting on region. 

burst key 

The dimension or level of a query in the 
report specification that is used to create, 
or burst, a set of report results. 

c 

CA See certificate authority. 

calculated member 

A member of a dimension whose measure 
values are not stored but are calculated at 
run time using an expression. 

canvas 

An area within a dashboard or workspace 
that users interact with to create, view, 
and manipulate content and data. 

capability 

A group of functions and features that 
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can be hidden or revealed to simplify the 
user interface. Capabilities can be enabled 
or disabled by changing preference 
settings, or they can be controlled through 
an administration interface. 

cardinality 

1 . For relational data sources, a 
numerical indication of the 
relationship between two query 
subjects, query items, or other model 
objects. 

2. For OLAP data sources, the number of 
members in a hierarchy. The 
cardinality property for a hierarchy is 
used to assign solve orders to 
expressions. 

cascading prompt 

A prompt that uses values from a 
previous prompt to filter the values in the 
current prompt or pick list. 

certificate 

In computer security, a digital document 
that binds a public key to the identity of 
the certificate owner, thereby enabling the 
certificate owner to be authenticated. A 
certificate is issued by a certificate 
authority and is digitally signed by that 
authority. See also certificate authority. 

certificate authority (CA) 

A component that issues certificates to 
each computer on which components are 
installed. 

CGI See Common Gateway Interface. 

cipher suite 

The combination of authentication, key 
exchange algorithm, and the Secure 
Sockets Layer (SSL) cipher specification 
used for the secure exchange of data. 

class style 

A combination of formatting 
characteristics, such as font, font size, and 
border, that the user names and stores as 
a set. 

CM See Content Manager. 

Common Gateway Interface (CGI) 

An Internet standard for defining scripts 
that pass information from a web server 
to an application program, through an 
HTTP request, and vice versa. 



condition 

An expression that can be evaluated as 
true, false, or unknown. It can be 
expressed in natural language text, in 
mathematically formal notation, or in a 
machine-readable language. 

constraint 

1 . A security specification that denies 
one or more users the ability to access 
a model component or to perform a 
modeling or authoring task. 

2. A restriction on the possible values 
that users can enter in a field. 

contact 

A named email address to which reports 
and agent e-mails can be sent. Contacts 
are never authenticated. 

content locale 

A code that is used to set the language or 
dialect used for browsers and report text, 
and the regional preferences, such as 
formats for time, date, money, money 
expressions, and time of day. 

Content Manager (CM) 

The service that retrieves information 
from the content store, and saves 
information to the content store. 

content store 

The database that contains the data 
needed to operate, such as report 
specifications, published models, and 
security rights. 

credential 

A set of information that grants a user or 
process certain access rights. 

cube A multidimensional representation of data 
needed for online analytical processing, 
multidimensional reporting, or 
multidimensional planning applications. 

custom set 

In Analysis Studio, a named object which 
can include filter rules, calculations, and 
sort rules. Custom sets can define a set of 
members that is different from any set 
originally defined in the cube model. See 
also predefined set, set. 



74 IBM Cognos Event Studio Version 10.2.0: User Guide 



D 

dashboard 

A web page that can contain one or more 
widgets that graphically represent 
business data. 

data source 

The source of data itself, such as a 
database or XML file, and the connection 
information necessary for accessing the 
data. 

data source connection 

The named information that defines the 
type of data source, its physical location, 
and any sign-on requirements. A data 
source can have more than one 
connection. 

data tree 

Within a studio, a structure that contains 
objects such as query subjects, query 
items, dimensions, levels, and members. 

A data tree is used as a palette of the 
available data that can be inserted into 
calculations, filters, display areas, and 
other authoring gestures. 

deployment 

The process of moving an application 
(such as a report or model) to a different 
instance. For example, reports are often 
created in a test environment and then 
deployed to production. When an 
application is deployed, it is exported, 
transferred, and imported. 

deployment archive 

A file used for deployment. A deployment 
archive contains the data from the content 
store that is being moved. 

deployment specification 

A definition of what packages to move 
(deploy) between source and target 
environments, the deployment 
preferences, and the archive name. 
Deployment specifications are used for 
import and export. 

derived index 

A calculated metric that provides a status 
and a score based on other metrics. 

details-based set 

A set based on an item and its immediate 
details. See also set. 



dimension 

A broad grouping of descriptive data 
about a major aspect of a business, such 
as products, dates, or locations. Each 
dimension includes different levels of 
members in one or more hierarchies and 
an optional set of calculated members or 
special categories. 

dimensional data source 

A data source containing data modeled 
using OLAP concepts, including 
dimensions, hierarchies, and measures. 

drill down 

In a multidimensional representation of 
data, to access information by starting 
with a general category and moving 
downwards through the hierarchy of 
information, for example from Years to 
Quarters to Months. 



event A change to a state, such as the 

completion or failure of an operation, 
business process, or human task, that can 
trigger a subsequent action, such as 
persisting the event data to a data 
repository or invoking another business 
process. 

event key 

A combination of data items that uniquely 
defines an event instance. Identifying an 
event instance enables the agent to 
determine if it is new, ongoing or 
stopped. 

event list 

The set of detected event instances 
evaluated by the task execution rules to 
determine which agent tasks should be 
performed. 



F 

fact See measure. 

G 

gateway 

An extension of a web server program 
that transfers information from the web 
server to another server. Gateways are 
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often CGI programs, but may follow other 
standards such as ISAPI and Apache 
modules. 

glyph The actual shape (bit pattern, outline) of a 
character image. For example, italic A and 
roman A are two different glyphs 
representing the same underlying 
character. Strictly speaking, any two 
images which differ in shape constitute 
different glyphs. In this usage, glyph is a 
synonym for character image, or simply 
image (The Unicode Standard - Version 
1 . 0 ). 

group A collection of users who can share access 
authorities for protected resources. 

grouping 

In reporting, the process of organizing 
common values of query items together 
and only displaying the value once. 

H 

hierarchy 

The organization of a set of entities into a 
tree structure, with each entity (except the 
root) having one or more parent entities 
and an arbitrary number of child entities. 



I 

information card 

A display of high-level information about 
dashboard, workspace, or report content, 
such as owner, contact information, date 
modified, and an optional thumbnail view 
of the dashboard, workspace, or report. 

information pane 

In Analysis Studio, a pane that helps the 
user to confirm their selection in the data 
tree by displaying related information, 
such as the level and attributes. 

initiative 

A task developed to achieve objectives or 
close the gap between performance and 
targets. Initiatives are associated with 
individual objectives and often known as 
projects, actions, or activities. 

item See member. 



J 

job A group of runnable objects, such as 
reports, agents, and other jobs that the 
user runs and schedules as a batch. 

job step 

The smallest part of a job that can be run 
separately. A job step can be a report or it 
can be another job. 



L 

layout The arrangement of printed matter on a 
screen or page, including margins, line 
spacing, type specification, header and 
footer information, indents, and more. 

level A set of entities or members that form 

one section of a hierarchy in a dimension 
and represent the same type of object. For 
example, a geographical dimension might 
contain levels for region, state, and city. 

locale A setting that identifies language or 

geography and determines formatting 
conventions such as collation, case 
conversion, character classification, the 
language of messages, date and time 
representation, and numeric 
representation. 

M 

MDX See Multidimensional Expression 
Language. 

measure 

A performance indicator that is 
quantifiable and used to determine how 
well a business is operating. For example, 
measures can be Revenue, 

Revenue /Employee, and Profit Margin 
percent. 

member 

A unique item within a hierarchy. For 
example. Camping Equipment and 4 Man 
tent are members of the Products 
hierarchy. 

metric A measure to assess performance in a key 
area of a business. 

metric extract 

A set of mappings between an existing 
Cognos data source and a Metric Studio 
object or value. For example, a cube 
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measure named Revenue is mapped to a 
Metric Studio metric named Revenue 
Actual Value. 

metric package 

In Cognos Connection, a representation of 
a Metric Studio application. A metric 
package contains connection information, 
reports, and metric management tasks for 
that application. See also package. 

metric store 

A database that contains content for 
metric packages. A metric store also 
contains Metric Studio settings, such as 
user preferences. 

metric type 

A category of metrics that defines the 
business rules such as performance 
pattern, units, and meaning of a group of 
metrics. For example. Revenue can be a 
metric type, and European Revenue and 
North American Revenue would be 
metrics of this type. 

model A physical or business representation of 

the structure of the data from one or more 
data sources. A model describes data 
objects, structure, and grouping, as well 
as relationships and security. In Cognos 
BI, a model is created and maintained in 
Framework Manager. The model or a 
subset of the model must be published to 
the Cognos server as a package for users 
to create and run reports. 

multidimensional data source 

See dimensional data source. 

Multidimensional Expression Language (MDX) 

The multidimensional equivalent of 
Structured Query Language (SQL). 



N 

named set 

See predefined set. 

namespace 

A part of the model in which the names 
may be defined and used. Within a 
namespace, each name has a unique 
meaning. 

news item 

A single entry in a Really Simple 
Syndication (RSS) compatible format. It 
can include a headline, text, and a link to 
more information. A news item task in an 



agent can be used to create news items 
for display in a Cognos Connection 
portlet. 



o 

object In Report Studio, an empty information 
container that can be dragged to a report 
from the Toolbox tab and then filled with 
data. Reports are made up of objects, 
which include crosstabs, text items, 
calculations, graphics, and tables. 

object extract 

An extract that defines the metadata for a 
Metric Studio object, such as a user 
defined column, a scorecard, or a data 
source. 



P 

package 

A subset of a model, which can be the 
whole model, to be made available to the 
Cognos server. See also metric package. 

page set 

In Report Studio, a set of one or more 
designed pages which repeat in the report 
output for each instance of a chosen 
query item. See also set. 

passport 

Session-based information, stored and 
encrypted in Content Manager memory, 
regarding authenticated users. A passport 
is created the first time a user accesses 
Cognos 8, and it is retained until a 
session ends, either when the user logs off 
or after a specified period of inactivity. 

portlet 

A reusable component that is part of a 
web application that provides specific 
information or services to be presented in 
the context of a portal. 

predefined set 

A set of members defined inside an OLAP 
data source as a list or by an expression. 
Predefined sets can be used in analysis 
and report authoring. See also custom set, 
set. 

product locale 

The code or setting that specifies which 
language, regional settings, or both to use 
for parts of the product interface, such as 
menu commands. 
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project 



1 . In Metric Studio, a task or set of tasks 
undertaken by a team and monitored 
on a scorecard. A project tracks dates, 
resources, and status. 

2. In Metric Designer, a group of 
extracts. Each extract contains the 
metadata that is used to populate the 
Metric Studio data store or to create 
applications. 

prompt 

A report element that asks for parameter 
values before the report is run. 

properties pane 

Within a studio, a pane that provides an 
overview of the properties for selected 
data. The properties pane can also be 
used to make several changes and apply 
them at the same time, instead of 
repeating several different commands. 

publish 

In Cognos BI, to expose all or part of a 
Framework Manager model or 
Transformer PowerCube, through a 
package, to the Cognos server, so that the 
data can be used to create reports and 
other content. 

Q 

query The simple report specifications created 
and edited by Query Studio. 

query item 

A representation of a column of data in a 
data source. Query items may appear in a 
model or in a report and contain a 
reference to a database column, a 
reference to another query item, or a 
calculation. 

query subject 

A named collection of query items that 
are closely functionally related. Query 
subjects are defined using Framework 
Manager to represent relational data and 
form the set of available data for 
authoring reports in Query Studio and 
Report Studio. A query subject is similar 
to a relational view in that it can be 
treated as a table but does not necessarily 
reflect the data storage. 



Really Simple Syndication (RSS) 

An XML file format for syndicated web 
content that is based on the Really Simple 
Syndication specification (RSS 2.0). The 
RSS XML file formats are used by Internet 
users to subscribe to websites that have 
provided RSS feeds. See also Rich Site 
Summary. 

repeater 

In Report Studio, a cell container that 
repeats values within itself with no 
predefined internal structure. 

repeater table 

In Report Studio, a table-like container 
that repeats cells across and down the 
page or row in the associated query. 

report A set of data deliberately laid out to 
communicate business information. 

report output 

The output produced as a result of 
executing a report specification against a 
data set. 

report specification 

An executable definition of a report, 
including query and layout rules, which 
can be combined with data to produce a 
report output. 

report view 

A reference to another report that has its 
own properties, such as prompt values, 
schedules, and results. Report views can 
be used to share a report specification 
instead of making copies of it. 

response file 

An ASCII file that can be customized with 
the setup and configuration data that 
automates an installation. During an 
interactive installation, the setup and 
configuration data must be entered, but 
with a response file, the installation can 
proceed without any intervention. 

Rich Site Summary (RSS) 

An XML-based format for syndicated web 
content that is based on the RSS 0.91 
specification. The RSS XML file formats 
are used by Internet users to subscribe to 
websites that have provided RSS feeds. 

See also Really Simple Syndication. 

RSS 
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1 . See Really Simple Syndication. 

2. See Rich Site Summary. 

s 

score A number or ranking that expresses 
applicability in relation to a standard. 

scorecard 

A collection of metrics representing the 
performance of one unit or aspect of an 
organization. 

scorecard structure 

The hierarchy of scorecards that reflects 
how an enterprise organizes its metrics. 

security provider 

See authentication provider. 

selection-based set 

A collection of individual items that the 
user has explicitly selected. The items or 
members may be selected from one or 
more levels of the same hierarchy. See 
also set. 

session 

The time during which an authenticated 
user is logged on. 

set A collection of related items or members. 
Members in a set may be specifically 
chosen, or selected by one or more filter 
rules. See also custom set, details-based 
set, page set, predefined set, 
selection-based set, stacked set. 

stacked set 

Two or more sets arranged one above 
another in rows or side-by-side in 
columns. See also set. 

strategy 

The overall plan of action (such as for a 
brand unit, business unit, channel, or 
company) to achieve a stated goal. 
Strategies normally cover a period of 
more than one year. 

strategy map 

In Metric Studio, a visual representation 
of the strategy and the objectives of that 
strategy for an organization. For example, 
a strategy map may show employees how 
their jobs are aligned to the overall 
objectives of the organization. 

summary 

In reporting and analysis, an aggregate 
value that is calculated for all the values 



of a particular level or dimension. 
Examples of summaries include total, 
minimum, maximum, average, and count. 



T 

task An action performed by an agent if the 
event status meets the task execution 
rules. For example, an agent can send an 
email, publish a news item, or run a 
report. 

task execution rule 

A user-specified option within an agent 
that determines which statuses and values 
cause a task to be run. It determines 
which tasks to execute for each event 
instance. 

template 

In report authoring, a reusable report 
layout or style that can be used to set the 
presentation of a query or report. 

thumbnail 

An icon-sized rendering of a larger 
graphic image that permits a user to 
preview the image without opening a 
view or graphical editor. 

tuple An ordered collection of two or more 

members from different dimensions. For 
example, the tuple (2007, Camping 
Equipment, Japan) returns the value for 
the intersection of the three members: 
2007, Camping Equipment, and Japan. 
Tuples can be used to filter and sort data, 
and to create calculations. 



u 

union set 

See stacked set. 

user Any individual, organization, process, 

device, program, protocol, or system that 
uses the services of a computing system. 

user-defined column 

In metric management, a column used to 
represent a value other than the actual or 
target. It may be an industry benchmark 
or any other useful additional numerical 
information for a period, including a 
calculation based on the other values of 
the metric. User-defined columns may be 
different for each metric type. 
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w 

watch list 

A list of metrics that each user has chosen 
to monitor closely. If notification is 
enabled in Metric Studio, the user will 
receive email notification of changes to 
these metrics. Users can also choose to 
display their watch list as a portlet within 
Cognos Connection. 

watch rule 

A user-defined condition that determines 
whether a report is delivered to the user. 
When the rule is run, the output is 
evaluated and, if it satisfies the condition 
or rule, the report is delivered by email or 
news item. Watch rules limit report 
delivery to those reports containing data 
of significance to the user. 

Web Services for Remote Portlets 

A standard for creating 
presentation-oriented web services so that 
they can be easily integrated within other 
applications, such as web portals. 

widget 

A portable, reusable application or piece 
of dynamic content that can be placed 
into a web page, receive input, and 
communicate with an application or with 
another widget. 

work area 

The area within a studio that contains the 
report, analysis, query, or agent currently 
being used. 

workspace 

See dashboard. 
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